BBS Toolkit/BBS Toolkit.iso/doors_1/ds40.zip/DS40.DOC

Text File | 1991-10-24 | 278KB | 6,645 lines

                         Door Source - Version 4.0
                      Copyrighted 1989,1989,1990,1991
                              By Todd Miller

                              Support Boards:
           PC-Technologies (Sysop Todd Miller)  [phone]


                               Mail Support:
                              PC-Technologies
                              PO Box 77103
                              Greensboro, NC 27417-7103
  Door Source 4.0
  Programmer's Manual - Page 2
                         Table of Contents

  Disclaimer and Credits.............................................4

  Introduction.......................................................5

  The deal on NO registration........................................6

  Some Never Nevers..................................................7

  Quick Start........................................................8
     Loading Door Source.............................................8
     First few lines.................................................8

  Getting Started....................................................10

  Command line options...............................................

  Door Writing Techniques............................................16
     Gathering data from the user....................................19
     Making friendly menus...........................................20

  Finishing your door................................................23

  Getting more out of Door Source....................................25
     The definable page sound........................................25
     Two fancier input prompts.......................................26

 Advanced Techniques................................................29
     Extra status line...............................................29
     Writing your own I/O routines...................................30

  How a door works...................................................32

  Converting from 3.2 or before......................................33

  Summary of new features............................................34

  Appendix A - CALL Syntax...........................................35

  Appendix B - Optimizing your door..................................36

  Appendix C - Common Questions......................................37

  Appendix D - Variable Reference....................................38

  Appendix E - Script Commands.......................................41

  Appendix F - Command Reference.....................................53
     AdjustTimeLimit.................................................54
     AllTrun$........................................................55
     ANSIMusic.......................................................56     BackSpace.......................................................57
     BackSpaceOver...................................................58
     BackSpaceToCol..................................................59
     BeepSpeaker.....................................................60
     BlockSend.......................................................61
     Center..........................................................62
     ChangeCTS.......................................................63
     ChangeDTR.......................................................64
     ChangeRTS.......................................................65
     CheckCarrier....................................................66
     CheckTimeLeft...................................................67
     ClrScrn.........................................................68
     ColorEasy.......................................................69
     CommInkey$......................................................70
     CommKeyInkey$...................................................71
     CopyAFile.......................................................72
     DayOfWeek.......................................................73
     DoorBusy........................................................74
     EntryIncomm.....................................................75
     ExtendedCode....................................................76
     ExitDoor........................................................77
     FileExist.......................................................78
     FileOpen........................................................79
     GameInfoUpdate..................................................80
     GetTime.........................................................81
     HighScores......................................................82
     Incomm..........................................................83
     MenuManager.....................................................85
     MoveCursor......................................................86
     NL..............................................................87
     Parser..........................................................88
     PromptIncomm....................................................89
     QSend...........................................................90
     RainbowSend.....................................................91
     RandNum.........................................................92
     ReadUsers.......................................................93
     Send............................................................94
     ShellToDos......................................................95
     Sorter..........................................................96
     SysopPage.......................................................97
     TimeConvert.....................................................98
     ViewFile........................................................99
     WaitASec........................................................100
     WindowInput.....................................................101
     WindowPrint.....................................................102
     Windows.........................................................103
     WriteUsers......................................................104  Door Source 4.0
  Programmer's Manual - Page 4

        Disclaimer and Credits
        ----------------------
    This software (including instructions for its use) is provided "as is"
    without warranty of any kine. Further, the author does not warrant,
    guarantee, or make any representations regarding the use, or the results
    of the use, of the software or written materials converning the software
    in terms of correctness, accuracy, reliabilty, currentnes, or otherwise.
    The entire risk as to the results and performance of the software is
    assumed by you. If the software or written materials are defective, you,
    and not the author, or the authors distributors or employees, assume
    the entire cost of all necessary servicing, repair, or correction.

    Neither the author nor anyone else who has been involved in the creation,
    production, or delivery of this software shall be liable for any direct,
    indirect, consequential, or incidental damages (including damages for
    loss of business profits, business interruption, loss of business
    information, and the like) arising out of the use of or inability of
    to use such software. Distribution of the software is allowed as long
    as it is in complete form as when you recieved it. Distribution of
    the libraries without the documentation is not allowed.

    Sorry for such a long disclaimer, but you have to cover that legal stuff.

    QuickBasic (R) is a registered trade mark of Microsoft Corporation

    PCBoard (R) is a registered trade mark of Clark Development Company (CDC)

    MS-DOS (R) is a registered trade mark of Microsoft Corporation

    Door Source is copyrighted Computer City, USA 1988, 1989, 1990, 1991


    Troy Getty - For helping in the testing of 4.0 and suggesting a
        badly needed routine, ShellToDOS.

    Daniel Sharpe - For letting us put the RainbowSend command into Door
        Source.

    Premo Mondone - Who has given me suggestions for 3.0 and above

    To all my competitors - Who give me inspiration to make this product
        better than theirs. (And cheaper too!)
  Door Source 4.0
  Programmer's Manual - Page 5

        Introduction
        ------------
           Welcome to Door Source! Door Source is a Quick Basic library,
    intended for using with versions 4.0 and above. Door Source provides
    you with a collection of routines to help you interface with a bulletin
    board and the communications port to make a "door", or otherwise
    referred to as a third party program, that adds onto the board.
           Some people don't like having to read a large manual, and rather
    jump right in with both feet and start off, if you would like to quickly
    start, please read the following two sections after this introduction.
    It is advised however, that you read Door Writing Techniques, and
    Getting More out of Door Source too. If you have previously used
    Door Source, you should refer to Converting from 3.2 or before and
    also to the Summary of New Features. Door Source will also be
    referred to as DS in this manual.
           Door Source is provided to you free of charge, and you can
    receive technical support at [phone] (DATA 2400 max).
    Door Source users will be given free access to the other nodes
    after first calling the number above.

        Files included
        --------------
           Here is a list of files that you should have:

                DS40    .DOC - Door Source 4.0 documentation
                DOORSORC.INT - Door Source 4.0 include file
                DSGAME  .INT - Door Source 4.0 include file
                WINDDEMO.BAS - Window demo using the Window routine
                MENUDEMO.BAS - Menu demo using the MenuManager routine
                PRMTDEMO.BAS - Prompts demo using various input routines
                BLCKDEMO.BAS - A demo using the UserBlock type declaration
                ERRDEMO .BAS - A demo with the CarrierLossError variable
                SAMPLE  .BAS - A sample door program written with Door Source
                MANUAL  .FRM - A form to order a printed manual with disks
                LOADQB  .BAT - A batch file to make loading DS easier
                DS00x   .DS4 - These are special files with extra routines
                DSINST  .EXE - This will help you select the right object
                               files for the most compact DS library.
                DSINST  .DOC - Documentation on how to use the installer
                COMPRESS.ZIP - A program to compress the HighScores data files
                DOORINST.ZIP - A program to install your doors on other boards
  Door Source 4.0
  Programmer's Manual - Page 6

        The deal on NO registration
        ---------------------------
           This may seem extremely odd, but Door Source is offered 100%
        completely free. There are no registration fees, no more forms,
        you don't ever have to send us a thing!
           Why? Many years ago when Door Source was first started on,
        I realized the need for a better product in the field of door
        tool kits, and I decided that I would try to fill that gap, but
        at no charge. All the other door kits (that I know of) ask for
        some kind of registration, and I think this is truly one of the
        first that requires none at all.
           But I do like to know who is using Door Source, and a call to
        PC-Technologies just to say thanks, or, better yet, to give a
        suggestion for improvements, is always appreciated! If you have
        a specific need for a routine or improvement to the Door Source
        library, you can call and tell it to me, and you're guaranteed
        that 90% of all improvements or suggestions are added within a
        few releases!

  Door Source 4.0
  Programmer's Manual - Page 7

        Some Never Nevers
        -----------------
           There are some things you never should do when using Door Source.
        What you shouldn't do is listed below, and since most people won't
        believe it unless they know why, we have included reasons, and
        in some cases, alternate routines to use instead.

        Never use CLS, VIEW PRINT, PRINT, LOCATE, or COLOR because
           Door Source handles all screen output, and using these
           will cause Door Source to lose some of its pointers on the
           screen. Also, on systems using DesqView, it could cause lock ups.

        Never use OPEN COM or ON COM, because Door Source doesn't use
           Quick Basic's communication routines, and using these would
           cause a confliction of interrupts between Door Source and
           Quick Basic, that would lead to unpredictable results.

        Never use SCREEN, because Door Source handles screen output,
           it wouldn't be able to follow your change to a different
           mode, and would cause serious problems.

        Never use END or SYSTEM, because that would cause Door Source
           to leave its interrupt handlers still in place and the
           next program to run would probably crash.

        Never use DEFINT, or any of DEF beside DEF FN, because
           Door Source expects variables to be passed that are in
           single precision format (the default of Quick Basic).

        Never use PLAY or SOUND, because it will cause a sound
           when the sysop using your door program may not want sound,
           like in the middle of the night, use BeepSpeaker instead
           of BEEP or SOUND, and AnsiMusic instead of PLAY.

  Door Source 4.0
  Programmer's Manual - Page 8

     Quick Start
     -----------

        Installing and loading Door Source
        ----------------------------------
           After you have unzipped the Door Source file (assuming that you
        have since you're reading this), you will only need to copy a few
        files into your Quick Basic sub-directory. All you will need to
        copy is DS40.QLB, DS40.LIB, and DOORSORC.INT. Now you are ready
        to load up Quick Basic, which you can do by typing:

           QB [your program name] /L DS40

           You also can add on a /CMD[command$ string] that would place
        what you put there into COMMAND$ inside Quick Basic. This would
        be used to easily specify your configuration file for the door,
        an example is this:

           QB MYDOOR /L DS40 /CMDTESTDOOR.CFG LOCAL

           Putting a space in between the /CMD and TESTDOOR.CFG will
        cause Door Source not to recognize your configuration file
        properly.

        The First Few Lines
        -------------------
           Once inside the Quick Basic environment, ready to write a
        new door program, the first line should always be:

        ' $INCLUDE:'DOORSORC.INT'

           This will tell Quick Basic to include this file into your
        program. What this file contains is declarations for the
        Door Source routines (to help eliminate errors), a COMMON SHARED
        block, along with a few CONSTant declarations. At the end of the
        file, it calls the InitDoor routine, which starts Door Source
        rolling. The next line after that in your program should be:

        PROGNAME$ = "My Door"

           You should replace "My Door" with the name of your door. But
        make sure that it is in quotations, or Quick Basic will give you
        a Type mismatch error. The name placed in this string shouldn't
        exceed 20 characters. The next line should be:

        RELEASE$ = "1.0"

           This is the release number (or version number) of your door
        program. It should be less than 6 characters long, and can contain
        letters and numbers (A-Z, a-z, 0-9), as well as punctuation.
  Door Source 4.0
  Programmer's Manual - Page 9

        CALL ClrScrn

           CALL ClrScrn should be the next line in your program. It will
        clear the screen, and now you almost ready to go on about your
        door, however, there is one last thing. In the DOORSORC.INT, when
        it calls InitDoor, it will leave a file open for you (file number 1)
        and this file is the configuration file. If you would like to
        INPUT anything from it, do that here, and once you are done inputing
        anything else that was added onto the configuration file, or if
        you didn't input anything at all, you will need to add one last
        line, which is:

        CLOSE #1

           Now you are ready to write your door. A few basic routines that
        you should look up are Send (on page XX), Incomm (on page XX),
        ClrScrn (on page XX), and NL (on page XX). I'm sure you are
        sick of reading this manual by now, but these are the 4 most
        basic commands. You should also read Testing Your Door before you
        try to run the door for the first time, because there are a few
        things to make sure that you have in your program, and on your
        disk in order for it to work.
  Door Source 4.0
  Programmer's Manual - Page 10

        Getting Started
        ---------------

        Writing a simple program in Door Source
        ---------------------------------------
           Before loading Quick Basic, make sure that you have set the
        proper environment strings to direct Quick Basic to your Door
        Source directory (if you have one).
           You will also need to make a configuration file that you
        can use to test a simple door with. The Door Source configuration
        file format is a simple four line file. You can make it longer
        if your door needs information from it (see Advanced Techniques).
        An example configuration file might be called TESTDOOR.CFG and look
        like this:

        C:\PCB\PCBOARD.SYS
        PC-Technologies
        Todd
        Miller

           The first line is a drive/path/filename to the bbs interface file,
        and the second line is the name of the bbs using the door. The third
        line is the first name of the sysop and the fourth line is the last
        name of the sysop.
           Now, load up Quick Basic, with the /L (library) switch on it like
        this:

        QB /L DS40

           That will load up Quick Basic and the Door Source library. Two other
        switches that you might use when loading Quick Basic are:

        /RUN             - This is put at the beginning of the line right after
                           QB and will make Quick Basic run the file specified.
        /CMDMYCONFIG.CFG - The /CMD option always comes at the end, and what
                           comes DIRECTLY after the /CMD will be loaded into
                           the COMMAND$, this simulates what you would have
                           if someone loaded your program like this:
                           MYDOOR MYCONFIG.CFG
                           The MYCONFIG.CFG would be put in the COMMAND$, but
                           if you want to test doors inside Quick Basic, you
                           should use this option, or set the COMMAND$ from
                           the Run menu in Quick Basic.

           Once Quick Basic is loaded, you should press ALT-R to get the
        Run menu, and the select Modify COMMAND$ (If it isn't listed, then
        go to the options menu and select Full Menus, then try again). Now
        enter in the name of the configuration file that you made earlier
        before loading (If you didn't make it, you can shell to dos from the
        File menu and make it there). Put after the configuration filename,
  Door Source 4.0
  Programmer's Manual - Page 11

        the word LOCAL. LOCAL will tell Door Source to read the configuration
        file, but not to use the BBS interface file. Door Source will prompt
        you for a name, and if you want to use ANSI graphics. This way, you
        don't have to worry about making a test PCBOARD.SYS, DORINFO1.DEF,
        CALLINFO.BBS, or DOOR.SYS. If you didn't specify LOCAL, it would look
        for the bbs interface file that you gave it.
           Now type the following program into Quick Basic:

        ' $INCLUDE:'DOORSORC.INT'
        PROGNAME$="Hello World"
        RELEASE$="1.0"
        CALL ClrScrn
        CLOSE #1

        CALL Send("Hello World!",No,Yes,10)
        CALL Incomm("How are you today, @FIRST@ ?",No,No,14)
        CALL ExitDoor

           Press the F5 key and the program will run. If you receive an
        error, refer to Common Questions to find a solution. You should
        see Door Source ask you for a name, and if you want ANSI graphics.
        Then the screen will clear and it will say Hello World! in High
        Intensity Green, and the beneath that it will show How are you today,
        with your first name. Enter in anything you want and press enter.
        It will then say Closing Door... and more. You'll also notice that
        at the bottom of the screen is a status line, and it will be
        discussed later in this section. Now let's find out how this
        program works.
           First, the INCLUDE file has a lot of DECLAREs in it and a
        COMMON SHARED block, it also makes a CALL to the Door Source
        routine InitDoor. Inside InitDoor, Door Source will read the
        configuration file, process the bbs interface file (in this
        case, it will ask you for your name and if you want ANSI
        instead), and it will set up the communications port if it
        is going to be used.
           In the next two lines, you set up two variables. PROGNAME$
        should be the name of your program. RELEASE$ should be the
        version number of your program. Door Source will display these
        on the status line. PROGNAME$ shouldn't be bigger than 20 characters
        and RELEASE$ shouldn't be bigger than 5 characters. They both
        can contain A-Z, a-z, 0-9, and punctuation.
           Then you make a call to the Door Source routine ClrScrn, which
        clears the screen (local and remote), and updates the status line.
        At this point, if you had added onto the configuration file, you
        would read it here, but since we didn't, we just close the file
        that InitDoor left open for us.
  Door Source 4.0
  Programmer's Manual - Page 12

           The first four lines of the program above should be the first
        four lines in all of your doors, except you would replace what
        PROGNAME$ and RELEASE$ with information for your door.
           Send is a Door Source routine that outputs (local and remote)
        a string, and can optionly beep the speaker, and send a enter when
        done. The number is the color number, here's the format for calling
        Send.

        CALL Send("Hello World!", No, Yes, 10)
                   ^              ^   ^    ^
                   |              |   |    Color to use
                   |              |   Send enter when done?
                   |              Beep the speaker when done?
                   What to output

           Incomm is another routine that outputs first and then waits
        for input back. There are many options that you can use with
        Incomm, most which are in global variables, which are covered
        in the reference for it. Here's the way to call Incomm:

        CALL Incomm("How are you today, @FIRST@ ?", No, No, 14)
                     ^                              ^   ^   ^
                     |                              |   |   Color to use
                     |                              |   Limit the length? If
                     |                              |   so, max length.
                     |                              Send enter before input?
                     What to output first

           You may have noticed how @FIRST@ wasn't displayed on the screen,
        but your first name was instead. That's because that when Door Source
        sees one of these, it knows to replace it with what you want instead.
        There is a complete list of these in Appendix D.
           The last call is to ExitDoor, which closes up Door Source files
        and removes the Door Source interrupt handlers. If you use END
        instead of ExitDoor, then the interrupt handlers will remain in
        place, causing the next program to run to crash. ExitDoor will
        also insure that the caller stays connected while he/she is transferred
        back to the bbs.

  Door Source 4.0
  Programmer's Manual - Page 13

        Colors
        ------
           Door Source can support foreground and background colors. There
        are three different ways that you can use and change colors too.
        Here's a color chart:

        #       Name           Hex     Foreground   Background
        0       Black           0          Y            Y
        1       Blue            1          Y            Y
        2       Green           2          Y            Y
        3       Cyan            3          Y            Y
        4       Red             4          Y            Y
        5       Magenta         5          Y            Y
        6       Brown           6          Y            Y
        7       White           7          Y            Y
        8       Gray            8          Y            N
        9       HiBlue          9          Y            N
        10      HiGreen         A          Y            N
        11      HiCyan          B          Y            N
        12      HiRed           C          Y            N
        13      HiMagenta       D          Y            N
        14      Yellow          E          Y            N
        15      HiWhite         F          Y            N

        Way #1 to use color
        -------------------
           CALL Send("Hello!",No,No,12)
           CALL Send("Bye!",No,Yes,10)

           This would output Hello! in high intensity red and on the same
           line it would put Bye! in high intensity green.

        Way #2 to use color
        -------------------
           CALL Send("Hello!",No,Yes,HiRed)
           CALL Send("Bye!",No,Yes,HiGreen)

           This would output the same thing as above, the only difference
           is that it is easier to read.

        Way #3 to use color
        -------------------
           CALL Send("Hello!@X0ABye!",No,Yes,12)

           This would output the same as the first and second way, but
           this one does it with one string. The whole key to this method
           is the @X0A code in the middle. It tells Door Source to change
           colors.

  Door Source 4.0
  Programmer's Manual - Page 14

        Color Code
        ----------
           Here's how to use the special color codes:

                @X0F
                ^^^^
                |||Foreground color
                ||Background color
                |Second part of signal code
                First part of signal code

           You can also change the background color by setting the
           variable BackGroundColor to a color number on the chart
           above that is valid a background color (0-7).

        Command Line Options
        --------------------
           Door Source has numerous command line options in order to provide
        flexibility with most computer systems. Here is a list:

                LOCAL       - Forces Door Source to run in local mode. This
                              is really meant for testing purposes, but it
                              still reads the configuration file, but doesn't
                              read the bbs interface file.
                NETWORK     - Forces file sharing to be active incase you
                              are using something other than SHARE to manage
                              file locking.
                IRQ=n       - Lets you change the IRQ used for the com port
                              specified in the bbs interface file.
                              (See below for more information)
                ADDR=&Hnnnn - Lets you change the address used for the com
                              port specified in the bbs interface file.
                              (See below for more information)
                PS2         - Forces the PS/2 IRQs and addresses if a PS/2
                              isn't detected (Normally it is, but you can't
                              always tell!)
                RBBS        - Forces Door Source into RBBS/QBBS mode
                WILDCAT     - Forces Door Source into Wildcat 2.0 mode
                DOORSYS     - Forces Door Source into 31-Line DOOR.SYS mode
                PCB121      - Forces Door Source into PCBoard 11.8/12.x mode
                              with COM 1 active
                PCB122      - Forces Door Source into PCBoard 11.8/12.x mode
                              with COM 2 active
                PCB14       - (DEFAULT) Forces Door Source into PCBoard 14.x
                              mode

  Door Source 4.0
  Programmer's Manual - Page 15

        When you use the IRQ or the ADDR option, you must include the other.
        You can't use just the IRQ and not the ADDR, and you can't use just
        the ADDR and not the IRQ. Here's a chart with the STANDARD IRQs
        and addresses for the PS/2s and IBM PCs:
                                Non PS/2
                Com port       IRQ     Address
                   1             4       &H3F8
                   2             3       &H2F8
                   3             4       &H3E8
                   4             3       &H2E8
                  5-8            4       &H3F8

                                PS/2
                Com port       IRQ     Address
                   1             4       &H3F8
                   2             3       &H2F8
                   3             3       &H3220
                   4             3       &H3228
                   5             3       &H4220
                   6             3       &H4228
                   7             3       &H5220
                   8             3       &H5228

  Door Source 4.0
  Programmer's Manual - Page 16

        Door Writing Techniques
        -----------------------
           When writing a door, you should keep three concepts in mind, they
        are:

        1) Compatibility
        2) Flexibility
        3) Multi-node

           A compatible door is a door that easily runs on several bbs types.
        Door Source currently supports PCBoard 11.8+, PCBoard 14.x, WildCat,
        RBBS/QBBS DORINFO1.DEF, and the 31-line version of DOOR.SYS. Modifying
        specific detailed parts of the user's information makes the door
        less portable, since not all systems have the same information as
        others.
           A flexible door is one that allows the sysop to EASILY tell the
        game where things are, and to set the options that they want.
        Options like a tournament mode, turns per day, plays per day, etc,...
        are good options to have. Letting the sysop define text from the
        door is stretching this a little, but some sysops like this feature.
        Of course it does mean a lot of work on your part too.
           A multi-node door is often the hardest to write, but not if you
        know how. Really it is very easy, easier than most think. You first
        have to decide how multi-node you want your door to get. For example,
        you might not won't to try to program something to let two players
        on at the same time attack each other, so maybe you don't let on
        go into the same sector as another that is currently on, or you
        could go for the more complex way and do a one-on-one active battle
        mode (which players would like). But the one thing all multi-node
        doors must do is to share files correctly, and the way to do this
        is to open files as SHARED, and to LOCK and UNLOCK individual records.
        You will also want to keep in contact with other nodes playing
        your door at the same time, and this can be done with a simple file
        that would be organized by node. It would tell the other nodes if
        it was running maintenance (so the others would play while it was), or
        to tell the other nodes where someone is. In the Door Source Door
        tool kit, it contains routines to maintain a file, and others to
        help make your door more multinode. A multi-node door is always
        praised by the sysops of a multi-node system.

        Quick Basic problems
        --------------------
           Quick Basic does have a few problems, and you will encounter them
        if you are working on a large door project. You will probably
        encounter a "Out of Stack Space" or a "Out of Data Space" error.
        I've found that exiting to DOS and then coming back will usually
        solve the problem. If not, then its time to do some work on your
        program. If you know that you're door will be large, or if your
        door gets larger than you expected, then here are a few tips on
        how to get rid of these problems, or to prevent them:
  Door Source 4.0
  Programmer's Manual - Page 17

                1) Use variables, not constants. When you call a routine,
                   like Send, and pass it a constant, the space that the
                   constant used is not released for other programs to use.
                   Instead, it stays in memory until your program quits.
                   So call Send or other routines this way, by defining your
                   variable first.

                        Lin$="Hello!":ColorToUse=10
                        CALL Send(Lin$, No, Yes, ColorToUse)

                   If you didn't set up the variables before hand, you
                   would have just used up 12 bytes of stack space that
                   wouldn't be made available for other things. (I didn't
                   miscount, a string has a 4 byte discriptor on it.)

                2) Use MAKEDS so that your Door Source library will be
                   as small as possible, and so it won't take up extra
                   space with routines you don't need.

                3) Use as few variables as possible. You should set aside
                   two or three variables for your loops, a few for input,
                   and a few for output, etc,... Just don't go around
                   putting in new variables, because it will eliminate
                   stack space.

                4) If you are using your own COMMON SHARED block, eliminate
                   all unnecessary variables from it, and don't declare
                   a function or subroutine as STATIC unless necessary.

        Large doors
        -----------
           When writing LARGE doors with Door Source, you should use
        a multi-module program. To create a new module, you must select
        the Create file option from the file menu (full menus only).
        Here are some tips for writing large doors:

                1) Make a COMMON SHARED block for each of your modules
                   that has commonly used variables.

                2) Include the DOORSORC.INT at the beginning of each module
                   so that it can use the Door Source routines and variables.

                3) Make as many things as possible a routine or a function,
                   and place those routines and functions into a module of
                   their own (You could even have several modules of routines).

                4) Remember that you can't GOTO or GOSUB to a line number or a
                   label in another module.

  Door Source 4.0
  Programmer's Manual - Page 18

                5) Anything that is done more than once is a good candidate for
                   routine or function, even if it just calculates a score
                   or shows lots of information.

                6) When calling routines (Door Source or your own), pass
                   variables, not constants to them.

  Door Source 4.0
  Programmer's Manual - Page 19

        Gathering Data from the User
        ----------------------------
           When writing your door, you will want to keep a consistent, but
        friendly and easy to use approach to receiving information back from
        the user. Using the PromptIncomm or EntryIncomm is a good way to
        gather a limited amount of data, PromptIncomm is most useful for
        yes and no questions, and for amounts. EntryIncomm is good for
        long replies (sentences, names, etc,...).
           You can also vary Incomm in a number of ways, the Incomm routine
        is the kernel for PromptIncomm and EntryIncomm. You can write your own
        routine to first do your special prompt and then call Incomm. For
        example, if you wanted to make a prompt that used RainbowSend so the
        prompt is lots of different colors, you could do this:

        SUB RainbowInput(Text$, LimitField)
           CALL RainbowSend(Text$, No, No, 11)
           CALL Incomm("", No, LimitField, Last.Clr.Used)
        END SUB

           This would be output Text$ (the prompt) using RainbowSend first,
        then use Incomm to receive the data. The variable, Last.Clr.Used, is
        a Door Source variable that has the number of the last color used
        stored in it.
           If you have specific keys that you want the user to use and to
        lock out the others, use the Table$ and Default.Table$ to limit
        the input to certain keys, for example:

           Table$="YN"
           CALL Incomm("Do you want to quit (Y/N) ? ", No, 1, 14)
           Table$=Default.Table$

           The above example first sets Table$ to equal YN, now Door Source
        will only allow the user to input the letters Y and N (Lower case
        will NOT work, you have to add in the lower case letters too!).
        The last line sets Table$ back to the default (when Door Source
        starts, Table$ is already at the default). This is very important
        so that you don't accidentally keep limiting input when you don't
        want to. Also, NEVER change Default.Table$, doing so will make it
        only harder on you to undo the Table$ setting. You don't have to
        worry about adding in characters like backspace or enter, because
        Door Source assumes that you will want to let the user use those
        keys. Table$ does not affect any output routines, only the Door
        Source input routines (except CommInkey$ and CommKeyInkey$ functions)

  Door Source 4.0
  Programmer's Manual - Page 20

        Making friendly menus
        ---------------------
           Friendly menus (to you and the user) are menus that can be
        aborted in the middle of display. To make a friendly menu in
        Door Source, define a array and put your menu in it. This also
        makes it easy for you to make a quick change to one or all of
        your menus if you have all of the arrays in the same place.
        An example of how to make a friendly menu would be:

        CONST Main.Menu.Length = 5

        DIM Main.Menu$(5)

        Main.Menu$(1)="(1) Quit"
        Main.Menu$(2)="(2) Quit"
        Main.Menu$(3)="(3) Quit"
        Main.Menu$(4)="(4) Quit"
        Main.Menu$(5)="(5) Quit"

        CALL BlockSend(Main.Menu$(), No, Main.Menu.Length)

           If the user was to press the space bar, CTRL-X, or CTRL-K while
        the menu was displaying, it would stop displaying and let your
        program go on to receive the input.
           Another form of the friendly menu (but doesn't allow aborting)
        is using MenuManager to display your menu, and allows ANSI users to
        use a scroll bar to scroll up and down and make their choice, and
        allows non-ANSI users to enter their selection.

        Presenting information in a compact format
        ------------------------------------------
           Displaying ten, twenty character long lines, on ten separate lines
        is a waste of space. Instead, you could compact the display to five
        lines, or even less. Setting TabSpace in between calls to one of the
        Send routines will let you make a nicely formatted display, for example:

           CALL Send("Info #1:"+Info1$, No, No, 10)
           TabSpace = 40
           CALL Send("Info #2:"+Info2$, No, Yes, 10)
           CALL Send("Info #3:"+Info3$, No, No, 10)
           TabSpace = 40
           CALL Send("Info #4:"+Info4$, No, Yes, 10)

        Would look like:

        Info #1: Something                      Info #2: Something else
        Info #3: Anything                       Info #4: Anything else!

  Door Source 4.0
  Programmer's Manual - Page 21

           If you want to display information from an array in a compact
        format, you could do this:

           Stack = 0
           FOR X = 1 TO 10
              IF Stack = 0 THEN
                 CALL Send("Info :"+Info$(X), No, No, 10)
                 TabSpace = 40
                 Stack = 1
              ELSE
                 CALL Send("Info :"+Info$(X), No, Yes, 10)
                 Stack = 0
              END IF
           NEXT X
           IF TabSpace = 40 THEN TabSpace = 0

           In the above example, the variable Stack changes from 0 to 1 and
        back again to keep track of whether or not it's time to tab over to
        column 40 or to end the line. The IF after the NEXT X makes sure that
        you aren't set at column 40 for your next output when you don't want
        to be.
           You could also put in another IF block inside the FOR loop to let
        you decide whether or not you have any information to display or not.
        You could also modify all the above examples so that you could have
        three columns and not just two.

        The Configuration File
        ----------------------
           You can make the configuration file for your door program larger
        than what Door Source requires it to be, and you can read in the
        information yourself too. Door Source automatically reads in the
        first four lines of the configuration file and sets everything up
        for you to read the rest. Reading more from the configuration file
        is simple:

        ' $INCLUDE:'DOORSORC.INT'
        ProgName$="Configuration Reader"
        Release$="1.0"
        LINE INPUT #1, ExtraInfo$
        LINE INPUT #1, ExtraNumber
        CLOSE #1
        CALL ClrScrn

           Even though there is no open statement, Door Source opened the
        file and read the information from it already (It did this from in
        the DOORSORC.INT). Remember to close the file after use, even if you
        don't use it at all. The only limit to how long your configuration
        file can be is the disk space and the amount of memory you can
        use to store the information. The configuration file can not be
        in a random access format, only sequential.
  Door Source 4.0
  Programmer's Manual - Page 22

        Testing your Door
        -----------------
           The easiest way to test your door is to run it from inside the
        Quick Basic environment. You first have to have three things done
        so that you can, and they are:

                1) Have a sample configuration file in the Quick Basic
                   directory.

                2) Load Quick Basic with the /L option and DS40 after it
                   For example:
                        QB /L DS40 /CMDTESTDOOR.CFG LOCAL

                3) Load Quick Basic with the /CMD option and your configuration
                   file's name after it with the word LOCAL.
                   (See above example)

           If you forgot to load with the /CMD option, you can set it from
        inside Quick Basic from the Run menu (Modify COMMAND$).
           Now all you have to do is press F5 to run your program. If you
        have any problems, refer to Appendix C - Common Questions.

  Door Source 4.0
  Programmer's Manual - Page 23

        Finishing your Door
        -------------------
           To eliminate all possible problems, you should first thoroughly test
        you door in two manners, logically, and unlogically. When you are
        logically testing it, you should use your door the way you designed
        it to be used, noting the little problems as you go. Then when you
        unlogically test it, you try testing your program in a way completely
        opposite of how you designed it. This method is a through method to
        debug your program. You will find most of the errors through this
        method, but then there are always situations that even you didn't
        think of in either of these manners.
           To finish a door you will need to compile to door into a EXE format.
        This way you can use the door without having to load QuickBasic to run
        your doors. Since Door Source doesn't use Quick Basic's communications
        routines, you CAN compile your door to be a stand-alone program, that
        doesn't need BRUN45.EXE. If you prefer to not make it a stand-alone,
        you do not have to use a patched version of BRUN45.EXE like other
        door packages require.
           In order to compile your program, you must go to the Run menu and
        select Make EXE. It will compile your program in memory and then
        a window will pop up asking what you want the final file name of the
        program to be, and other options. Do not select the produce debug
        code option, it will only make your program larger and slower, and
        allow people to break it in the middle by pressing CTRL-Break. After
        you have everything like you want it, select one of the button on the
        bottom of the window to start the process.
           Of course, you'll need to provide some documentation for your
        door, and good documentation should have some of these sections listed
        here:
                Table of contents
                Disclaimer
                Overview/Summary of the door
                List of files in archive
                Configuration file setup
                Command line options
                Batch file setup
                Customization instructions
                List of function/ALT keys
                Possible errors/Troubleshooting

           A good disclaimer is always something that is hard to come by, here
        is a disclaimer that pretty much covers you:

                This program and other files associated with it are not
                guaranteed to be bug free or virus free. We are not
                responsible for any damages of any kind, including
                profit loses and data loss, that relate directly or
                indirectly to these programs and files. You may
                distribute this program, as long as it is in unmodified
                form with all the files originally included.
  Door Source 4.0
  Programmer's Manual - Page 24

           You may wish to add/change/delete something from this one, but it
        is a pretty good one. A overview or summary of the door would be a
        simple explanation of exactly what your door does, no specifics
        really. The configuration file section should show a sample
        configuration file, and give a sentence or two on each line in the
        file. The command line options should show the user how to
        configure the door to run with his system. Refer to the chapter
        on command line options to put into your documentation.
           The batch file setup should show a few example batch files, and
        telling you if you need to add it in your daily event, etc,...
        The customization section should tell the sysop that uses your door
        how to better customize it to what he needs. Some examples might be
        aliases allowed/not allowed, location of files, prompts, etc,...
           The list of function keys is basically this:

                  F3  - Printer toggle
                  F4  - Page bell toggle
                  F5  - Shell to DOS
                  F7  - Caller alarm toggle
                  F8  - Return caller to board
                  F10 - Start sysop chat
                  ESC - Enter sysop chat
                ALT-X - Drop to DOS after caller logs off
                ALT-N - Sysop next on flag

           Troubleshooting should list a few possible errors that might
        occur, and how to solve them. Like if error number 53 (File not found)
        occurs, then search your configuration file for a misspelled filename
        or a wrong path. If error 61 (Disk full) occurs, free up disk space.
        Some errors can't be solved, and you could list those and have them
        call a bulletin board for more help.

  Door Source 4.0
  Programmer's Manual - Page 25

        Getting more out of Door Source
        -------------------------------

        This section and the following section, Advanced Techniques, are
        very closely related. With Door Source 4.0, it is basically possible
        for you to write your own input and output routines using out base
        routines to do the dirty work. The difference in between this section
        and the next is simply that this tells you how to take advantage of
        some of the new variables and features, and the next section tells
        you more on programming more advanced things with Door Source.

        The definable page sound
        ------------------------

           You can easily change the sound of the SysopPage routine by
        setting 3 variables - PageSound.1, PageSound.2, and PageSound.3
        The sound generated is in the order of PageSound.1, then PageSound.2,
        and then the final sound is PageSound.3. The numbers you put in
        PageSound should be in the acceptable range of the SOUND command,
        which is somewhere around 45-32767. A page sound of 200, 400, 600
        would make a sound that starts out low, then the next sound is
        about double the pitch of the first, and the third is double the
        pitch of the second. Its possible to create a variety of different
        sounds with this, try experimenting with the SOUND command first to
        find what you like the best. The duration of the sounds is set, and
        can't be changed.
                Example:
                PageSound.1=200
                PageSound.2=400
                PageSound.3=600
                CALL SysopPage(Answered)

        Filtering your input
        --------------------

           Sometimes, you may want to limit the input to a question to a
        few letters, or selectively not recognize certain characters. To
        do so, you should set the Table$ variable. An example would be:
                Example:
                Table$ = "YNyn"
                CALL Incomm("You can only type Y and N:",No,1,15)
                ' Anything else besides Y,N,y,n that the user types is
                ' not displayed or recognized. Backspace and enter CAN NOT
                ' be filtered out.
                Table$ = Default.Table$
                ' This is necessary to reset the filter back to normal,
                ' if you didn't do this then you'll have problems with
                ' later Incomm commands still being restricted with the
                ' filtering.
                Output:
                You can only type Y and N:Y  Door Source 4.0
  Programmer's Manual - Page 26

        Protecting input from prying eyes
        ---------------------------------

           When a password or something secret needs to be concealed, you
        can now set a "substitution character" that will be displayed in
        place of what the user really types. You can make the character
        anything you wish, but making it a null turns it off.
                Example:
                Protected.Input$="*" ' Now shows a * in place of text
                CALL Incomm("Password:", No, No, 15)
                Protected.Input$=""  ' Turns it off - Back to normal display
                Output:
                Password:******

        Two fancier input prompts
        -------------------------

           EntryIncomm
           -----------
           EntryIncomm prints out a field of (----) above the area where
           the user's input will be displayed. The size of the field is based
           on how big you make the field. Good for ANSI and NON-ANSI!
                Example:
                CALL EntryIncomm("Your new name:", 25, LightGreen, Yellow)
                '                                  ^ Field size
                Output:
                             (-------------------------)
                Your new name:Zantigahicatal

           PromptIncomm
           ------------
           PromptIncomm is most useful in ANSI cases, but will handle
           non-ansi well too, but the purpose of the routine is defeated
           then. What it does is create a field similar to the EntryIncomm
           but the field is on the same line as the input. The second text
           field is the "default field" tells the user what it defaults to
           if they press enter, but its up to you to interpret them pressing
           enter. You can pass a string as the second parameter, and it
           will use that instead of one of the already programmed constants.
           The constants are:
                Default1 = (Enter=no)
                Default2 = (Enter=none)
                Default3 = (Enter=quits)

                Example:
                CALL PromptIncomm("Do you wish to quit",Default1,
                        LightGreen, 1, Yellow)
                '                   ^ Field size
                Output:
                Do you wish to quit (Enter=no) ? (N)  Door Source 4.0
  Programmer's Manual - Page 27

           Unabortable ViewFiles
           ---------------------
           Do you want to force the user to see out an entire file? Its easy
           to block the abort codes by setting the variable No.Abort to YES,
           then when the user tries to abort, it won't let him. However, if
           more prompts are still offered, answering NO to it will stop the
           display.
                Example:
                No.Abort = YES
                CALL ViewFile("MYFILE.ANS", No, No, No)
                No.Abort = NO   ' Reset it back to normal

           Disabling carrier checking
           --------------------------
           How would you like to turn off carrier checking for a
           call back verification program of some sort, or something
           along those lines? Try setting Carrier.Check to YES, and
           Door Source will *IGNORE* the carrier detect flag. If the
           user drops carrier, you'll have to handle and detect yourself!
                Example:
                Carrier.Check = No  ' Disables carrier checking
                Carrier.Check = Yes ' (Default) enables carrier checking

           Checking the baud and the carrier, setting DTR, CTS, and RTS
           ------------------------------------------------------------

              Checking the baud rate
              ----------------------
              The variable Baud& has the baud rate stored in it. Here's
              what the number in it means:
                        1       - Local mode
                        300     - 300 baud
                        1200    - 1200 baud
                        2400    - 2400 baud
                        4800    - 4800 baud
                        9600    - 9600 baud
                        19200   - 19,200 baud
                        38400   - 38,400 baud
                        115200  - 115,200 baud

              Checking the carrier
              --------------------
              The routine CheckCarrier will tell you if a carrier is
              present.
                Example:
                CALL CheckCarrier(CarrierFlag)
                IF CarrierFlag = NO AND Baud& > 1 THEN
                   CALL ExitDoor  ' Carrier lost!
                END IF

  Door Source 4.0
  Programmer's Manual - Page 28

              Setting the DTR, CTS, and RTS
              -----------------------------

                DTR
                ---
                The DTR (Data Terminal Ready) when on normally means that
                you are on-line, and have a connection. However, on most
                modems, turning it off while it is on will break the
                connection.
                        Example:
                        CALL ChangeDTR(YES)   ' Turn DTR on
                        CALL ChangeDTR(NO)    ' Turn DTR off

                CTS Control On/Off
                ------------------
                CTS (Clear To Send) is used to signal the other modem that
                it is ok to send characters. Modems that don't preform
                error checking or UARTS that don't have buffers may require
                CTS flow-control to be on during high-speed file transfers.
                        Example:
                        CALL ChangeCTS(YES)   ' Turn CTS control on
                        CALL ChangeCTS(NO)    ' Turn CTS control off

                RTS
                ---
                RTS (Request To Send) is used by most auto-dial modems to
                see if a computer is ready to receive data from the modem.
                If the RTS signal isn't detected, some modems may refuse
                to accept modem commands or send result codes.
                        Example:
                        CALL ChangeRTS(YES)   ' Turn RTS on
                        CALL ChangeRTS(NO)    ' Turn RTS off

           Automatic more prompts
           ----------------------
           If you're displaying lots of information, like programmed in
           documentation, and you don't want to keep track of when you
           need to show a more prompt or a press any key prompt, just
           simply set the AutoMore variable to one of the settings:
                0                              Disables the prompts (default)
                MorePrompt    (Or the value 1) Causes automatic more prompts
                PressKeyPromp (Or the value 2) Causes automatic press any key
                Example:
                    AutoMore = MorePrompt
           The variable Lines.Since will tell you how many lines have been
           sent SINCE the last ClrScrn WITH one of the Send routines or
           Incomm routines. The automatic prompts are by default not
           enabled, and when enabled, they occur every 23 lines.

  Door Source 4.0
  Programmer's Manual - Page 29

        Advanced Techniques
        -------------------
           Door Source has several new features that are more program
        related, that are just a little bit to hard to put in the previous
        section, Getting more out of Door Source.

           The extra line status line
           --------------------------
           Normally, Door Source has lines 24 and 25 in use with its status
           line, but if you have some information of you're own that you'd
           like to put on it, now you can by using the GameInfoUpdate
           routine with the variable GameInfoCol.
           The only major change you have to make to your program is to use
           the DSGAME.INT file instead of the DOORSORC.INT file, and you'll
           need to write a routine to do the status line updating.
           First of all, the Door Source status line is moved up to lines
           23 and 24, and we leave 25 for your use. You call the
           GameInfoUpdate routine like you would call print, for example:
                ' $INCLUDE:'DSGAME.INT'
                  .
                  .  (Later in the program)                         Background
                  .                                                     \/
                CALL GameInfoUpdate("This is on the 25th line!", No, 14, 7)
                                     ^ Text                      ^   ^
                                                                 |   Foreground
                                                                 Enter
           The background is the last number, and the color you specify is
           the foreground color. The enter parameter is like the ; on a
           print command, telling it no keeps the current position at that
           spot, but yes will start at column 1 when you do the next
           GameInfoUpdate.
           But what if you want to position the cursor somewhere on the
           line without printing to that location? Or what if you want
           to know where the cursor is? You can tell both of these by
           looking at the GameInfoCol variable. For example:
                A = GameInfoCol   ' A now contains the horizontal position
                                  ' of the cursor on line 25.
                GameInfoCol = 30  ' With the next GameInfoUpdate call, it
                                  ' will start printing at column 30.
           Now the only thing missing is your interfacing this into your
           program. The easiest way to do this is to write a new ClrScrn
           routine, that you call in place of ClrScrn, this is necessary
           because ClrScrn doesn't update your line when called, so you'll
           have to do it. Here's an example of a new ClrScrn:
              SUB ClearTheScreen
                 CALL ClrScrn
                 CALL GameInfoUpdate("This is on the 25th line!",No,14,7)
              END SUB

  Door Source 4.0
  Programmer's Manual - Page 30

           Writing your own output routines
           --------------------------------
              With Door Source, you can virtually write your own output
           routines for use with your program. The kernel for all of our
           output routines is the Send1Line routine. It will send one
           line out to the local and remote display, and will decode the
           substitution codes too! All that's left for you to do is to
           write your own routine that calls this routine. For example,
           say you wanted to write a routine that would colorize all of the
           letters that are the capital A, then you might do this:
              SUB ColorizeTheA(Text$,AColor$,RegularColor$)
                 FOR X=1 TO LEN(Text$)
                    IF MID$(Text$,X,1)="A" THEN
                       CALL Send1Line(AColor$+MID$(Text$,X,1))
                    ELSE
                       CALL Send1Line(RegularColor$+MID$(Text$,X,1))
                    END IF
                 NEXT X
              END SUB
           The variables AColor$ and RegularColor$ would store the @X color
           codes for the colors for A's and other letters.

           Writing your own input routines
           -------------------------------
              You can write your own input routines too with Door Source.
           The main kernel for the input routine is CommInkey$, and a few
           other routines supplement the features offered in Incomm. An
           example input routine that is very simple might be:
              SUB GetInput
                 DO
                    A$=CommInkey$
                    IF A$="" THEN A$=INKEY$
                 LOOP UNTIL A$<>""
                 ARG$=A$
              END SUB
           You should also be aware that all filters, and special variables
           that affect input with Incomm do NOT work with CommInkey$, you
           have to program in support for them yourself if you want them.
           The GetInput routine above would wait for a key to be pressed
           on the local or remote keyboard. Now say that you want to echo
           the character to the screen and to the remote screen, you'd do
           this:
              SUB GetInput
                 DO
                    A$=CommInkey$
                    IF A$="" THEN A$=INKEY$
                 LOOP UNTIL A$<>""
                 ARG$=A$
                 CALL Send1Line(A$)   ' Echos the character
              END SUB
  Door Source 4.0
  Programmer's Manual - Page 31

           Now maybe you want to trap the function keys, you could do this:
              SUB GetInput
                 DO
                    A$=CommInkey$
                    IF A$="" THEN A$=INKEY$
                 LOOP UNTIL A$<>""
                 ARG$=A$
                 IF LEFT$(A$,1)=CHR$(0) THEN
                    CALL ExtendedCode(A$,NULL) ' Process the function key
                 ELSE
                    CALL Send1Line(A$)         ' Echos the character
                 END IF
              END SUB
           The NULL variable on the ExtendedCode is used only by Incomm,
           and you shouldn't pass anything to it in place of it, and its
           not used to return anything to your program. Now the GetInput
           routine we have above is pretty good. It will accept input
           from the keyboard and from remote, check for a extended code
           and process it, otherwise it will echo the character.
           You can also write your own chat routine, but use our code
           by calling Incomm with the second parameter as a 5. This
           will print the "Sysop started chat at" and the "Hello, this is"
           lines, and then will handle the input and color for you, then
           once the sysop presses ESC to end the chat, it will print the
           "Sysop ended chat at" and return control to you. So basically, by
           passing a 5 as the second parameter forces a chat.
              Example:
              CALL Incomm("",5,No,15)   ' Forces a chat

           Carrier loss processing
           ----------------------
              Sometimes in more complex doors, its necessary to process
           a carrier drop yourself in order to save and wrap up files.
           You could turn carrier checking off, but its best if you use
           the CarrierLossError method. What you do is set CarrierLossError
           to YES and when carrier is dropped, a error number 255 will be
           forced, and if you have a ON ERROR trapping processing in your
           program, you will be able to catch it, and then let Door Source
           finish off the rest. For an example, please refer to the example
           program ERRDEMO.BAS.

  Door Source 4.0
  Programmer's Manual - Page 32

        How a door works
        ----------------
           Understanding how a door works is good to know so that you can
        better plan your door. Here's a simple diagram on what happens:

                        BBS Creates the interface file and exits
                                         \|/
                                Door's batch file is run
                                         \|/
             |-->      Door loads and reads in the interface file
             |                           \|/
Door Source  |      The door opens the communications port if needed
handles this |                           \|/
with your    |                 User interacts with the door
program      |                           \|/
             |-->  Door eventually exits, updating the interface file
                                         \|/
                       BBS reloads and reads in the interface file
                                         \|/
                              User continues using the bbs

        The DOORSORC.INT file sets up the necessary DECLAREs for the routines
        and the functions, it then sets up the COMMON SHARED block which lets
        you share variables with Door Source, like Baud&. Then it sets up
        a few constants, and then calls InitDoor, then the Door Source library
        takes over, and reads the configuration file, initialize its variables
        and then opens the com port for access. Then control is returned to
        you and your program picks up from their setting the program's name
        and version, etc,... While you're doing other processing, Door Source
        is ALWAYS looking at the com port, keeping received data in its
        buffer until you're ready for it. Door Source monitors everything
        for you, from carrier detection to characters being sent to
        characters being received, all behind the scenes.

  Door Source 4.0
  Programmer's Manual - Page 33

        Converting from Door Source 3.2 or before to 4.0
        ------------------------------------------------
           There are a few changes in how you call routines from 3.2 and
        before. Here's the list and how to change your program to fit 4.0
        without major restructuring. The easiest way to change things is
        using the QuickBasic search and replace feature from the edit menu.

         * Routine AllTrun is now a function, you use it like this:
                A$ = AllTrun$(A$)
         * Routine HighScores has a extra parameter. The new third parameter
           lets you output its output to a already open file by passing the
           file number, but if you pass a 0, it outputs to the screen.
                CALL HighScores(Score, ScoreDataFile$, OutputFileNumber)
         * Routine Windows has a few parameters changes, the text foreground
           and text background have been deleted since WindowPrint and
           WindowInput do all window processing. Windows in your program
           will need to be re-written because of this.
                CALL Windows(ULR, ULC, LRR, LRC, Foreground, Background,
                        Border, Shadow)
         * Routine Windows has two new borders, they are:
                3 - Double horizontal Single vertical
                4 - Single horizontal Double vertical

         * Routine DayOfWeek moved into ScriptCMD.
                I1$="DAYOFWEEK":CALL ScriptCMD
         * Routine MenuManager parameters have been changed, the Select$
           parameter has been deleted, since now ANSI.Select$ and
           NonANSI.Select$ (COMMON SHARED variables) are now used for the
           select string. BarForeground and BarBack have been added, they
           have the foreground and background color for the selection bar.
                CALL MenuManager(Menu$(),Center,TextColor,NumberOfSelections,
                   BarForeground, BarBackground, BarnumberSelected)
         * Routine SysopPage now has an extra parameter, this extra one is
           used to return a variable in, not to pass one. It returns a 1 (YES)
           if the page was answered.
                CALL SysopPage(Answered)
         * Routine ErrorLevelSet has been removed because of environment
           conflicts.

  Door Source 4.0
  Programmer's Manual - Page 34

        Summary of new features
        -----------------------
                LOCAL command line switch added
                NETWORK command line switch added
                Up.Key$ and Down.Key$ variables added
                SysopPage changed
                PageSound.1, PageSound.2, and PageSound.3 added
                Page.String$ added
                F5 (Shell to DOS) added
                F3 (Printer toggle) added
                GameInfoUpdate routine added
                GameInfoCol added
                Table$ and Default.Table$ added
                PromptIncomm routine added
                No.Abort added
                MenuManager changed
                Parser changed
                WindowPrint and WindowInput routines added
                ExtendedCode routine added
                Protected.Input$ added
                BlockSend routine added
                RainbowSend routine added
                Windows routine changed
                DayOfWeek routine moved into ScriptCMD
                RandNum function fixed
                EntryIncomm added
                AllTrun routine changed into a function
                CheckCarrier routine added
                Baud& variable added
                CarrierLossError added
                Carrier.Check added
                ChangeDTR, ChangeCTS, and ChangeRTS added
                IRQ command line parameter added
                ADDR command line parameter added
                PS2 command line parameter added
                HighScores changed
                ALL ROUTINES optimized to run faster, and to be more compact

  Door Source 4.0
  Programmer's Manual - Page 35

        Appendix A - CALL Syntax
        ------------------------

        CALL QSend(Text$, Enter)
        CALL BackSpace(Text$)
        CALL ExtendedCode(Text$,NULL)
        CALL BeepSpeaker()
        CALL NL(Number.Of.Lines)
        CALL Send(Text$, Bell, Enter, Color.To.Use)
        CALL Incomm(Text$, Enter, Limit.Field, Color.To.Use)
        CALL ANSIMusic(Music$, Music)
        CALL GameInfoUpdate(Text$, Enter, Color.To.Use, Color.Background)
        CALL BackSpaceOver()
        CALL Center(Text$)
        CALL ClrScrn
        CALL ColorEasy(Text$, Color.To.Use, Enter)
        CALL DoorBusy()
        CALL ErrorLevelSet(Error.Level)
        CALL ExitDoor()
        CALL GetTime(Hours, Minutes, Seconds, SinceMid#)
        CALL HighScores(Score, Score.FileName$, OutputFileNumber)
        CALL MenuManager(Menu$(), Center, TextColor, Number.Of.Bars,
           Select.Color, BarForeground, BarBackground, BarSelected)
        CALL MoveCursor(X,Y)
        CALL Parser(SearchFor$, SearchIn$, Array$(), ErrCode)
        CALL ReadUsers(ErrCode)
        CALL ScriptCMD()
        CALL Sorter(Array$(), How.Many.Elements)
        CALL SysopPage(Answered)
        CALL TimeConvert(Hours, Minutes, New.Time$)
        CALL ViewFile(FileName$, Check.For.GFile, MorePrompts, EnterPrompt)
        CALL WaitASec(How.Many.Seconds.To.Wait)
        CALL Windows(ULR, ULC, LRR, LRC, Fore, Back, Border, Shadow)
        CALL WriteUsers(ErrCode)
        CALL BlockSend(Array$(), Center, Lines.To.Send)
        CALL WindowPrint(Text$, Row, Col, Fore, Back)
        CALL WindowInput(Text$, MaxLength, Row, Col, Fore, Back)
        CALL RainbowSend(Text$, Bell, Enter, Color.To.Use)
        CALL PromptIncomm(Text$, Default$, DefaultColor, LimitField,
           Color.To.Use)
        CALL EntryIncomm(Text$, LimitField, FieldColor, Color.To.Use)
        CALL ShellToDos(Shell.String$)

  Door Source 4.0
  Programmer's Manual - Page 36

        Appendix B - Optimizing your door
        ---------------------------------
           The best way to optimize a door program can be divided into two
        parts.
                1) The first part is cleaning up your code. This would mean
                   elimination of most or all GOTOs and GOSUBs, elimination
                   of as many constants as possible, and elimination of
                   repetition in your code.
                2) The second part is compiling from the command line.
                   QuickBasic compiles with some unneeded options when you
                   select the Make EXE command from the Run menu. You might
                   need the error trapping flag (/X) if you have a ON ERROR
                   statement in your program, and you might need the switch
                   for dynamic arrays (/AH) if you're using them. Here's a
                   sample compilation for a NON-STANDALONE program:
                      BC MYPROG;
                      LINK /EX MYPROG.BAS,MYPROG.EXE,,BRUN45.LIB+DOORSORC.LIB

                   For a STANDALONE program, use this:
                      BC MYPROG/O;
                      LINK /EX MYPROG.BAS,MYPROG.EXE,,BCOM45.LIB+DOORSORC.LIB

                   These parameters will compile the to the most compact
                   format. You can also use PKLITE to compress it more.

  Door Source 4.0
  Programmer's Manual - Page 37

        Appendix C - Common Questions
        -----------------------------
        Q: How do I read in additional information from the configuration
           file?
        A: To read in more information, simply INPUT from file #1 after you
           call ClrScrn for the first time. Make sure to close it when you're
           done. Here's an example:
              ' $INCLUDE:'DOORSORC.INT'
              PROGNAME$="Example"
              RELEASE$="1.0"
              CALL ClrScrn
              INPUT #1, ExtraInfo
              CLOSE #1
           Door Source doesn't read past the fourth line of the configuration
           file, so you can put whatever you please there.
        Q: How do I test a door from inside QuickBasic?
        A: You must have first loaded QuickBasic with the /L option specifying
           the Door Source library. For example:
              QB MYDOOR /L DOORSORC
           Then you will need to setup the command line parameters by setting
           the COMMAND$, you do this from the Run menu from Modify COMMAND$.
           Now, as long as your configuration file, bbs interface file, and
           all other files you need exist, you can press F5 and test your door
           from QuickBasic.
        Q: Should I compile as a stand-alone door?
        A: It's up to you. A stand-alone door will not need the BRUN45.EXE,
           but it will make your door significantly larger, and compiling
           not as a stand-alone will save space. Door Source will work fine
           either way.
        Q: What does the error "Error opening port -1" mean?
        A: It means that you have specified a invalid serial port, and you
           should check your bbs interface file or your bbs's setup.

  Door Source 4.0
  Programmer's Manual - Page 38

        Appendix D - Variable Reference
        -------------------------------
        The first part of this reference is of the global variables, the
        second is of the global UserBlock type declaration.

        Variable Name   Purpose
        -------------   ------------------------------------------------------
        ARG$            Input from user, returned by Incomm routine
        SYSDPATH$       Drive/Path/Filename of bbs interface file
        BBSName$        Name of BBS running on
        SysopNM$        Sysop FULL name
        CALLNAME$       Caller's FULL name
        Baud&           Baud rate of caller
        PROGNAME$       Name of your door
        RELEASE$        Version of your door
        ANSI            Ansi Flag  (1 = On  0 = Off)
        I1$,I2$,I3$     Input variables to script commands
        O1$,O2$,O3$     Output variables from script commands
        User.Color      Color that user input will be display in
        BackGroundColor Color to use for background when displaying
        Exit.Dor.1$     First line of ExitDoor message
        Exit.Dor.2$     Second line of ExitDoor message
        Exit.Dor.Clr1   Color of first line
        Exit.Dor.Clr2   Color of second line
        UserF$          First name of caller
        UserL$          Last name of caller
        Caps            Convert all input to caps (1 = Yes  0 = No)
        Page.Bell       Page bell toggle (-1 = On  0 = Off)
        Caller.Alarm    Caller alarm (-1 = On  0 = Off)
        Sysop.Next      Sysop next on toggle (-1 = On  0 = Off)
        Hang.Up         Exit to DOS after log off toggle (-1 = On  0 = Off)
        User.Record     Record number of user
        Network         Network active (1 = Yes  0 = No)
        Display.Toggle  Display on/off toggle (ignored by DS -1 = On  0 = Off)
        Printer.Toggle  Printer on/off (-1 = On  0 = Off)
        BusyFlag        A signal to ExitDoor that DoorBusy routine is in use
        UserFile$       Drive/Path/Filename of USERS file (PCBoard ONLY!)
        Up.Key$         Key to be used for scrolling up in MenuManager
        Down.Key$       Key to be used for scrolling down in MenuManager
        Parity          Parity of user calling (7 or 8 data bits)
        Filter          Incomm filtering active (filters all high ascii out)
        BusyFile$       Drive/Path/Filename of busy file for DoorBusy routine
        SysFirst$       Sysop's first name
        SysLast$        Sysop's last name
        CommPort        Communacations port being used (1-8)
        Last.Clr.Used   Last color used in a call to Send
        EchoKey         STOPS echoing keys to remote user (1 = Yes  0 = No)
        No.Enter.Send   Incomm doesn't send enter when done (1 = Yes  0 = No)
        File.Missing$   String ViewFile$ displays when file is not found
        BBSType$        Type of BBS in use (PCB14, PCB121, PCB122, WILDCAT,
                        RBBS, or DOORSYS)  Door Source 4.0
  Programmer's Manual - Page 39

        Node            Node caller is on
        TabSpace        Send will tab to this column before sending
        InverseText     Reverses the text colors (Foreground/Background switch)
        Sysop           Sysop is on (1 = Yes  0 = No)
        BlinkText       Send will make text blink
        Not.Around$     String to show when Sysop doesn't answer page
        PARAM$          Extra command-line parameters that DS didn't use
        Page.String$    String to display while paging
        PageSound.1     First tone of page
        PageSound.2     Second tone of page
        PageSound.3     Third tone of page
        GameInfoCol     Column to start printing on game status line
        Default.Table$  Table containing a unaltered filter
        Table$          Specific filtering of characters for Incomm
        KeyBoardTimeOut Number of SECONDS for a keyboard time out
        Protected.Input$  Incomm displays this instead of what user types
        ANSI.Select$    Menu Manager's ANSI selection string
        NonAnsi.Select$ Menu Manager's NON-ANSI selection string
        Carrier.Check   Disables carrier checking (1 = Yes  0 = No)
        CarrierLossError  Causes ExitDoor to generate a error 255 if carrier
                          is dropped.
        No.Abort        Disables CTRL-X, CTRL-K keys from aborting screens
                        (1 = Yes  0 = No)
        AutoMore        Automatically prints more prompts/press any key prompts
        Lines.Since     Number of lines printed since last more/press prompt


  Door Source 4.0
  Programmer's Manual - Page 40

        This is the reference for the UserBlock global variable

  Variable                Type          P  W  R  D   Description
 -------------------     -----------    -  -  -  -   -------------------------
 CityState            AS STRING * 24    Y  Y  Y  Y   City and state of user
 Password             AS STRING * 12    Y  Y     Y   User's Password
 BusinessPhone        AS STRING * 13    Y        Y   User's Business/Data phone
 VoicePhone           AS STRING * 13    Y  Y     Y   User's Voice/Home phone
 LastDateOn           AS STRING * 20    Y  Y     Y   Last date user was on
 LastTimeOn           AS STRING * 5     Y            Last time user was on
 ExpertMode           AS STRING * 1     Y  Y     Y   Expert mode "Y" or "N"
 ProtocolType         AS STRING * 5     Y  Y     Y   Protocol selected
 LastDirListing       AS STRING * 10    Y  Y         Last date viewed dir
 SecurityLevel        AS INTEGER        Y  Y  Y  Y   Security Level for user
 TimesOn              AS INTEGER        Y  Y     Y   Number of times on before
 PageLength           AS INTEGER        Y  Y         Page length for user
 TotalUploads         AS INTEGER        Y  Y     Y   Total # of uploads made
 TotalDownloads       AS INTEGER        Y  Y     Y   Total # of downloads made
 DailyDownloadBytes   AS DOUBLE         Y            # of download bytes left
 UserComment          AS STRING * 30    Y            User Comment field
 SysopComment         AS STRING * 30    Y            Sysop Comment field
 ElapsedTime          AS INTEGER        Y  Y         Elapsed Time on system  1
 Subscription         AS STRING * 20    Y
 SubscriptionExpire   AS STRING * 20    Y
 AreaRegistration     AS STRING * 50    Y  Y     Y   Areas user has access to
 AreaExpire           AS STRING * 50    Y
 AreasToScan          AS STRING * 50    Y
 TotalDownloadBytes   AS DOUBLE         Y  Y     Y   Total bytes downloaded
 TotalUploadBytes     AS DOUBLE         Y            Total bytes uploaded
 DeleteFlag           AS STRING * 1     Y            Flag to delete user
 TimeEnteredDoor      AS STRING * 5     Y  Y  Y  Y   Time user entered door
 AreaFrom             AS INTEGER        Y        Y   Area user exited from
 MemorizedMessage     AS LONG           Y            Memorized message #
 TimeCalled           AS STRING * 5     Y  Y         Time user called bbs
 DailyDownloadTotal   AS INTEGER           Y         Total downloads TODAY
 MaxDownloadLimit     AS DOUBLE            Y         Max downloads TODAY
 LastRead             AS INTEGER           Y         Message last read
 MaxDownloadKLimit    AS DOUBLE         Y  Y     Y   Max d/l K TODAY
 ExpirationDate       AS STRING * 10             Y
 LR0                  AS STRING * 4     Y
 LR1                  AS STRING * 4     Y
 LR2                  AS STRING * 4     Y
      .
      .
 LR39                 AS STRING * 4     Y


  Door Source 4.0
  Programmer's Manual - Page 41

        Appendix E - Script Commands Reference
        --------------------------------------
        Script commands are several small routines packed all into one.
        In order to access them, you set the according variables, and
        then make a call to ScriptCMD routine. For example, if you
        wanted to display a Press [ANY KEY] to continue prompt, you
        could do this:
                I1$ = "PRES"
                CALL ScriptCMD
        Variables I1$, I2$, and I3$ are all INPUT variables that store
        information for the routine to use. O1$, O2$, and O3$ are all OUTPUT
        variables that return information from the routine to you.
        I1$ is always the name of the routine you're calling inside of
        ScriptCMD. You only have to specify the first 4 letters of the
        word unless stated in the documentation.


  Door Source 4.0
  Programmer's Manual - Page 42

        LTRIM

        Purpose: To trim all leading spaces

        Name in ScriptCMD: LTRIM

        Remarks: This routine is a simple truncation routine to remove
        all leading spaces from a string.

        Parameters Passed:
                I2$ - The string to be truncated

        Parameters Returned:
                O1$ - The truncated string


  Door Source 4.0
  Programmer's Manual - Page 43

        RTRIM

        Purpose: To trim all trailing spaces

        Name in ScriptCMD: RTRIM

        Remarks: This routine is a simple routine to truncate all trailing
        spaces from a string.

        Parameters Passed:
                I2$ - The string to be truncated

        Parameters Returned:
                O1$ - The truncated string


  Door Source 4.0
  Programmer's Manual - Page 44

        Upper Case

        Purpose: To convert a string to all upper case

        Name in ScriptCMD: UPPER

        Remarks: This routine will convert a string into all upper case

        Parameters Passed:
                I2$ - The string to be converted

        Parameters Returned:
                O1$ - The converted string


  Door Source 4.0
  Programmer's Manual - Page 45

        Lower case

        Purpose: To convert a string to all lower case

        Name in ScriptCMD: LOWER

        Remarks: This routine will convert a string into all lower case

        Parameters Passed:
                I2$ - The string to be converted

        Parameters Returned:
                O1$ - The converted string


  Door Source 4.0
  Programmer's Manual - Page 46

        More Prompt

        Purpose: To display a more prompt

        Name in ScriptCMD: MORE

        Remarks: This will display a more prompt and allow the user to
        select Yes to continue, No to abort, and C to go non-stop. It
        will return a Y (for yes), a N (for no), or a C (for non-stop)
        in O1$

        Parameters Passed: None

        Parameters Returned:
                O1$ - Contains a Y, N, or C


  Door Source 4.0
  Programmer's Manual - Page 47

        Press Any Key

        Purpose: To display a Press [ANY KEY] to continue prompt

        Name inside ScriptCMD: PRESS

        Remarks: This will display a Press [ANY KEY] to continue prompt and
        then wait for the key to be pressed:

        Parameters Passed: None

        Parameters Returned: None


  Door Source 4.0
  Programmer's Manual - Page 48

        Exist

        Purpose: To check if a file exists

        Name inside ScriptCMD: EXIST

        Remarks: This will check for the existence of the file specified.

        Parameters Passed:
                I2$ - Drive/Path/Location of file to check for

        Parameters Returned:
                O1$ - If the file exists
                      (Y = Yes  N = No)


  Door Source 4.0
  Programmer's Manual - Page 49

        Name conversion

        Purpose: To convert a name into proper upper and lower case

        Name inside ScriptCMD: NAMECASE

        Remarks: This will take a name like "DR. JOHN DOE" and properly
        convert it into "Dr John Doe"

        Parameters Passed:
                I2$ - The name to be converted

        Parameters Returned:
                O1$ - The converted name


  Door Source 4.0
  Programmer's Manual - Page 50

        Coding and Decoding

        Purpose: To code and decode a string

        Name inside ScriptCMD: CODER

        Remarks: This is a simple coding routine that will resist causal
        attempts to break it. It will code and decode with the same password.
        The longer the password, the better the protection you will have.
        The password shouldn't have any high ASCII characters in it.

        Parameters Passed:
                I2$ - String to be coded/decode

                I3$ - Password to code/decode with

        Parameters Returned:
                O1$ - The coded/decoded string


  Door Source 4.0
  Programmer's Manual - Page 51

        Reverse Bits

        Purpose: To reverse the bits in a string

        Name inside ScriptCMD: REVERSEBITS (MUST USE ENTIRE NAME!)

        Remarks: This will take all of the characters in a string and reverse
        it's bits. This is a simple, but easy to break coding routine. To
        unreverse the bits, just call the routine again.

        Parameters Passed:
                I2$ - The string to bit reverse

        Parameters Returned:
                O1$ - The bit reversed string


  Door Source 4.0
  Programmer's Manual - Page 52

        Reverse Characters

        Purpose: To reverse the order of characters in a string

        Name inside ScriptCMD: REVERSECHARS (MUST USE ENTIRE NAME!)

        Remarks: This changes the order of characters in a string so that
        the first is last, and the last is first, and so on throughout the
        entire string. To decode it, simply call the routine again.

        Parameters Passed:
                I2$ - The string to be reversed

        Parameters Returned:
                O1$ - The reversed string


  Door Source 4.0
  Programmer's Manual - Page 53

        Appendix F - Command Reference
        ------------------------------

        Each command is shown in a set format. The format is as follows:

        Name of routine

        Purpose: States the prupose of the routine

        Remarks: Tells you the general information on the routine and how
        to use it.

        Parameters Passed: Tells you what parameters to the routine and what
            they are for.

        Parameters Returned: Tells you what parameters are returned and what
            is in them.

        Example: A short little program showing the usage of the routine

        See Also: (on some routines) Gives you a reference to other routines
            that do nearly the same thing or that work with this routine.
  Door Source 4.0
  Programmer's Manual - Page 54

        AdjustTimeLimit

        Purpose: To adjust the user's time remaining

        Syntax: CALL AdjustTimeLimit(Minutes)

        Remarks: This will adjust the user's time remaining up or down
        depending on the number you pass it.

        Parameters Passed:
                Minutes - The number of minutes to increase the user's time

        Parameters Returned: None

        Example:
                CALL AdjustTimeLimit(10)     ' Give 10 minutes
                CALL AdjustTimeLimit(-10)    ' Take 10 minutes

  Door Source 4.0
  Programmer's Manual - Page 55

        AllTrun$

        Purpose: To truncate all leading and trailing spaces from a string

        Syntax: Text$ = AllTrun$(Text$)

        Remarks: This will remove all of those leading and trailing spaces
        that are a result of random file input, use of STR$, and other
        functions of BASIC.

        Parameters Passed:
                Text$ - The string to remove leading and trailing spaces from

        Parameters Returned:
                Text$ - The string without leading and trailing spaces

        Example:
                Text$ = "   These extra spaces will be removed   "
                Text$ = AllTrun$(Text$)
  Door Source 4.0
  Programmer's Manual - Page 56

        ANSIMusic

        Purpose: To play ANSI music to those users who can use it

        Syntax: CALL ANSIMusic(Music$, Music)

        Remarks: Some communacations programs can support and play ANSI music
        but not all of them. Qmodem, for example, will play ANSI music. You
        should ask your users near the beginning of the program "Do you have
        ANSI music?" and if they answer yes, then set Music to Yes (1)
        otherwise set it to No (0). You don't have to use Music, but whatever
        variable you store that value in should always be the second parameter
        of the call to this routine. The music string can be anything that
        the BASIC command PLAY would be able to play. The local speaker
        won't play the music unless the page bell is on.

        Parameters Passed:
                Music$ - The music to be played

                Music - If the user supports ANSI music or not
                        (1 = Yes  0 = No)

        Parameters Returned: None

        Example:
                Music = Yes
                Music$ = "ABCDEFG"
                CALL ANSIMusic(Music$, Music)

  Door Source 4.0
  Programmer's Manual - Page 57

        BackSpace

        Purpose: To backspace on the local and remote screen and also erase
        the proper character in the string passed

        Syntax: CALL BackSpace(Text$)

        Remarks: This will allow you to write your own input routines for
        use, and when a user presses the backspace key, call this routine and
        it will send the proper backspacing codes and erase the backspaced
        character from the string passed.

        Parameters Passed:
                Text$ - A string that will the backspace will be preformed on

        Parameters Returned:
                Text$ - The new string with the last character erased

        Example:
                IF KeyPressed$ = CHR$(8) THEN
                   CALL BackSpace(Text$)
                END IF

  Door Source 4.0
  Programmer's Manual - Page 58

        BackSpaceOver

        Purpose: To erase what is already on a line

        Syntax: CALL BackSpaceOver

        Remarks: This routine will backspace over everything to column 1,
        erasing everything on that line. If you have a prompt that you'd
        like to erase or something, this is the routine to call to erase
        it.

        Parameters Passed: None

        Parameters Returned: None

        Example:
                CALL BackSpaceOver

        See Also: BackSpaceToCol


  Door Source 4.0
  Programmer's Manual - Page 59

        BackSpaceToCol

        Purpose: To backspace over to the specified column

        Syntax: CALL BackSpaceToCol(Col)

        Remarks: This will backspace over from the current column all the
        way to the column specified. This is useful if the user inputed a
        improper response to a prompt and you want to erase just the user's
        input.

        Parameters Passed:
             Col - The column to backspace over to

        Parameters Returned: None

        Example:
                CALL Send("Backspace to here->this will be erased!",No,No,10)
                CALL BackSpaceToCol(20)

        See Also: BackSpaceOver

  Door Source 4.0
  Programmer's Manual - Page 60

        BeepSpeaker

        Purpose: To sound the local and remote speaker

        Syntax: CALL BeepSpeaker

        Remarks: Calling BeepSpeaker instead of sending a bell code to the
        screen and com port is better since it will always beep the remote
        speaker but won't make the local speaker sound unless the page bell
        is on.

        Parameters Passed: None

        Parameters Returned: None

        Example:
                CALL BeepSpeaker

  Door Source 4.0
  Programmer's Manual - Page 61

        BlockSend

        Purpose: To send a large amount of information to both displays

        Syntax: CALL BlockSend(Array$(), Center, Lines.To.Send)

        Remarks: This will send a large pre-programmed amount of data
        to the local and remote displays. Color can only be set and
        changed via @X codes. This routine is good for programmed in
        documentation, or menus.

        Parameters Passed:
                Array$() - The array to be displayed

                Center - Center text to be displayed

                Lines.To.Send - Number of array elements to display

        Parameters Returned: None

        Example:
                Array$(1) = "This will be displayed"
                Array$(2) = "Using the BlockSend routine"
                CALL BlockSend(Array$(), No, 2)

        See Also: ColorEasy, RainbowSend, Send, QSend

  Door Source 4.0
  Programmer's Manual - Page 62

        Center

        Purpose: To aid in centering strings for output

        Syntax: CALL Center(Text$)

        Remarks: This will strip out all @X codes and substitute in the
        proper text for substitution codes and will then set TabSpace to
        equal the correct column to make the string look centered. The
        string that you pass is NOT modified by this routine. This routine
        also will NOT print out the results but only set TabSpace.

        Parameters Passed:
                Text$ - The string to be centered

        Parameters Returned: None

        Example:
                Text$ = "This will be centered!"
                CALL Center(Text$)
                CALL Send(Text$, No, Yes, 10)
  Door Source 4.0
  Programmer's Manual - Page 63

        ChangeCTS

        Purpose: To raise or lower the CTS flag

        Syntax: CALL ChangeCTS(OnOff)

        Remarks: This will turn on or off the CTS (Clear To Send) flag
        which is used to tell the other modem that it is okay to send
        characters. Modem that don't preform error checking or UARTS
        that don't have buffers may require CTS flow-control to be on
        during high speed file transfers.

        Parameters Passed:
             OnOff - Whether you want the CTS on or off
                     (1 = Yes(On)  0 = No(Off))

        Parameters Returned: None

        Example:
             CALL ChangeCTS(No)         ' Turns CTS off

        See Also: ChangeDTR, ChangeRTS
  Door Source 4.0
  Programmer's Manual - Page 64

        ChangeDTR

        Purpose: To raise or lower the DTR

        Syntax: CALL ChangeDTR(OnOff)

        Remarks: If you want to drop the carrier on someone, this is one of
        the best ways to do it. Turning the DTR off normally will cut a person
        off-line, but not always.

        Parameters Passed:
             OnOff - Whether you want the DTR on or off
                     (1 = Yes(On)  0 = No(Off)

        Parameters Returned: None


        Example:
             CALL ChangeDTR(No)         ' Turns off DTR

        See Also: ChangeCTS, ChangeRTS


  Door Source 4.0
  Programmer's Manual - Page 65

        ChangeRTS

        Purpose: To raise or lower the RTS flag

        Syntax: CALL ChangeRTS(OnOff)

        Remarks: The RTS (Request To Send) flag is uesd by most auto-dial
        modems to see if a computer is ready to recieve data from the modem.
        If the RTS signal isn't detected, some modems may refuse to accept
        modem commands or send result codes.

        Parameters Passed:
             OnOff - Whether you want the RTS on or off
                     (1 = Yes(On)  0 = No(Off))

        Parameters Returned: None

        Example:
             CALL ChangeRTS(No)         ' Turns RTS off

        See Also: ChangeDTR, ChangeCTS

  Door Source 4.0
  Programmer's Manual - Page 66

        CheckCarrier

        Purpose: To check if a carrier is present

        Syntax: CALL CheckCarrier(CarrierPresent)

        Remarks: This will (as long as Carrier.Check is set to 0) return
        a Yes (1) or a No (0) in the parameter depending on if the carrier
        is present. If the global variable Carrier.Check is set to 1, then
        this routine will return ALWAYS a Yes (1).

        Parameters Passed: None

        Parameters Returned:
             CarrierPresent - Tells if the carrier is present
                              (1 = Yes  0 = No)

        Example:
             CALL CheckCarrier(CarrierPresent)
             IF CarrierPresent = Yes THEN
                CALL Send("You're still connected!", No, Yes, 10)
             END IF
          Door Source 4.0
  Programmer's Manual - Page 67

        CheckTimeLeft

        Purpose: To tell you how many minutes a user has left on the system

        Syntax: TimeRemaining = CheckTimeLeft

        Remarks: This function will return the number of minutes that the user
        currently on has left for this call. Be careful not to assign the
        value returned to a variable named TimeLeft because doing so will
        modify Door Source's variable and cause the user's time to go berserk!

        Parameters Passed: None

        Parameters Returned:
                TimeRemaining - The number of minutes left the user has

        Example:
                CALL Send("("+STR$(CheckTimeLeft)+" min. left )", No, No, 14)

        See Also: AdjustTimeLimit

  Door Source 4.0
  Programmer's Manual - Page 68

        ClrScrn

        Purpose: To clear the local and remote screens

        Syntax: CALL ClrScrn

        Remarks: This will effectively clear the screen for both sides
        using the fastest method that the caller can use. Setting
        BackGroundColor previous to calling this routine will cause the
        entire screen to be that color!

        Parameters Passed: None

        Parameters Returned: None

        Example:
                CALL ClrScrn

  Door Source 4.0
  Programmer's Manual - Page 69

        ColorEasy

        Purpose: To colorize a string and output it

        Syntax: CALL ColorEasy(Text$, Color.To.Use, Send.Enter)

        Remarks: If you have a string that you'd like to colorize without
        having to bother with multiple calls to Send or with @X codes, then
        use this routine. It will colorize A-Z, a-z, 0-9, and punctuation
        all in different colors. The Color.To.Use that you specify will
        affect the output of color over the whole text, experiment with
        different values to best fit what you need.

        Parameters Passed:
                Text$ - The string to be colorized and displayed

                Color.To.Use - This will vary the output for the different
                               colors used in coloring the text

                Send.Enter - Send a CR/LF sequence once displaying is finished

        Parameters Returned: None

        Example:
                Text$ = "This will be VERY colorful!!"
                CALL ColorEasy(Text$, 10, Yes)

        See Also: BlockSend, RainbowSend, Send, QSend

  Door Source 4.0
  Programmer's Manual - Page 70

        CommInkey$

        Purpose: To get a key from just the remote keyboard

        Syntax: Character$ = CommInkey$

        Remarks: This works just like INKEY$ and CommKeyInkey$, except it
        will take input ONLY from the com port. If there are no characters
        waiting to be read, then it will return a null.

        Parameters Passed: None

        Parameters Returned:
             Character$ - The character read from the com port

        Example:
             DO
             LOOP UNTIL (CommInkey$ <> "") OR (INKEY$ <> "")

        See Also: CommKeyInkey$
  Door Source 4.0
  Programmer's Manual - Page 71

        CommKeyInkey$

        Purpose: To get one character from the local or remote keyboard

        Syntax: Character$ = CommKeyInkey$

        Remarks: This will check the local keyboard and the com port buffer
        for keys waiting to be read, if one is found, it will read it and
        return it, otherwise it will return a null. If you want to wait for
        a key to be pressed, you should put this routine in a WHILE loop.

        Parameters Passed: None

        Parameters Returned:
                Character$ - Either null (if no key was pressed local or
                             remote) or a key from the keyboard or com port
                             buffer.

        Example:
                DO
                   Character$ = CommKeyInkey$
                LOOP UNTIL Character$ <> ""

        See Also: Incomm, CommInkey$
  Door Source 4.0
  Programmer's Manual - Page 72

        CopyAFile

        Purpose: To quickly copy a file without shelling to DOS

        Syntax: CALL CopyAFile(Source$, Destination$, ErrCode)

        Remarks: This will copy a file without the pitfalls of shelling to
        DOS to do it or of special complex programming. It will return
        a error code if an error occured.

        Parameters Passed:
             Source$ - Drive/Path/Filename of the file to be copied

             Destination$ - Drive/Path/Filename of the file to be created

        Parameters Returned:
             ErrCode - If a error occured during the copy
                       (1 = Yes  0 = No)

        Example:
             Source$ = "MYFILE.TXT"
             Destination$ = "MYFILE2.TXT"
             CALL CopyAFile(Source$, Destination$, ErrCode)
  Door Source 4.0
  Programmer's Manual - Page 73

        DayOfWeek

        Purpose: To calculate the which day of the week it is

        Syntax: Day = DayOfWeek

        Remarks: This routine will return a value from 1 to 7 indicating
        which day of the week it is. A 1 is Sunday, 2 is Monday, and so on.

        Parameters Passed: None

        Parameters Returned:
                Day - A number from 1-7 representing the day of the week

        Example:
                IF DayOfWeek = 1 THEN
                   CALL Send("It's SUNDAY!", No, Yes, 14)
                ELSE
                   CALL Send("It's not sunday!", No, Yes, 10)
                END IF
  Door Source 4.0
  Programmer's Manual - Page 74

        DoorBusy

        Purpose: To keep a door from being used by two nodes at once

        Syntax: CALL DoorBusy

        Remarks: If you aren't going to program multi-node support, call
        this routine so that multinode systems won't have problems running
        your door. You have to set the global variable BusyFile$ to the
        drive/path/filename of a "lockout file" that will be the signal
        to other nodes that the door is in use. If another node is using your
        door, then this routine will call DoorBusy and not return control
        to your program.

        Parameters Passed: None

        Parameters Returned: None

        Example:
                BusyFile$ = "MYDOOR.NET"
                CALL DoorBusy
  Door Source 4.0
  Programmer's Manual - Page 75

        EntryIncomm

        Purpose: To provide a field showing maximum length of input for prompt

        Syntax: CALL EntryIncomm(Text$, MaxLength, FieldColor, Color.To.Use)

        Remarks: This is a handy routine to for larger fields (3 characters and
        larger) that lets the user know what the limit is on the field size by
        printing above the prompt a (------) field indicator showing the
        maximum number of characters allowed.

        Parameters Passed:
                Text$ - Prompt to display

                MaxLength - Maximum number of characters to allow for input
                            (Required to be greater than 1)

                FieldColor - The color of the (---) field above the prompt

                Color.To.Use - The foreground color for the prompt itself

        Parameters Returned:
                ARG$ - The input received

        Example:
                See PRMTDEMO.BAS

                Text$ = "Enter your name:"
                CALL EntryIncomm(Text$, 20, 10, 11)
                ' This would output
                '                (--------------------)
                ' Enter your name:

        See Also: PromptIncomm, Incomm
  Door Source 4.0
  Programmer's Manual - Page 76

        ExtendedCode

        Purpose: To let you trap F-keys in your own I/O routines

        Syntax: CALL ExtendedCode(CodeToProcess$, NULL)

        Remarks: If you are writing your own version of Incomm, and would
        like to take advantage of Door Source's F-Key processing routines,
        call this with the key pressed and it will take the necessary
        action, which may be updating the status bar or shelling to DOS.

        Parameters Passed:
                CodeToProcess$ - The two character code of the key pressed

                NULL - This variable shouldn't be used by your routine, it
                is only used by Door Source and is specified only to maintain
                compatibility.

        Parameters Returned: None

        Example:
                A$ = INKEY$
                IF LEN(A$)>1 THEN               ' Extended code
                   CALL ExtendedCode(A$, NULL)
                END IF
  Door Source 4.0
  Programmer's Manual - Page 77

        ExitDoor

        Purpose: To close the com port and update the bbs interface file

        Syntax: CALL ExitDoor

        Remarks: Whenever you want to end your door, you MUST call this
        routine. NEVER let your door simply just come to an end or have the
        END or SYSTEM command in it. This routine will uphold the DTR and
        cleanup Door Source's variables, handlers, etc,... It will also
        update the bbs interface file with the current information. After
        calling this routine, control will not be returned to your door.

        Parameters Passed: None

        Parameters Returned: None

        Example:
                CALL ExitDoor


  Door Source 4.0
  Programmer's Manual - Page 78

        FileExist

        Purpose: To detect is a file exists on a disk

        Syntax: Exists = FileExist(FileName$)

        Remarks: If you're opening files or preforming something with files
        you should check, before attempting use, if they exist and not assume
        that they are there, otherwise your program will generate a error
        and most likely crash the board it was running on.

        Parameters Passed:
                FileName$ - Drive/Path/Filename to the file to be checked for

        Parameters Returned:
                Exists - If the file exists or not
                         (-1 = Yes  0 = No)

        Example:
                IF FileExist("MYFILE.FIL") THEN
                   CALL Send("It exists!", No, Yes, 12)
                END IF
  Door Source 4.0
  Programmer's Manual - Page 79

        FileOpen

        Purpose: To aid in opening files in a better, easier way

        Syntax: FileNumber = FileOpen(FileName$, Access$, Sharing, Length)

        Remarks: When you want to open a file and you don't know what the
        next available file number is, or you don't want to refer to files
        by their number, or if you don't want to have to fool with checking
        if a network is active every time a file is opened, this routine
        is what you should call. It will find the next available file number
        and open the file according to your specifications and return the
        file number to you in a variable so you can use it in place of a
        number.

        Parameters Passed:
                FileName$ - This is the name of the file to be opened
                Access$ - The method in which you want to open the file
                          for access.
                                I - Sequential Input
                                O - Sequential Output
                                A - Append (Write at end of file)
                                R - Random Read/Write
                                B - Binary Read/Write
                Sharing - Will open files to be shared if specified and a
                          network is active
                          (1 = Yes  0 = No)
                Length - For random and binary files only, this will open
                         the file with this as the record length.

        Parameters Returned:
                FileNumber - This is the variable you'd use for I/O with the
                             file. It will contain a -1 if the file wasn't
                             found that you tried to open only if you're
                             trying to do sequential input.

        Example:
                FileNumber = FileOpen("MYFILE.FIL", "O", Yes, 0)
                PRINT #FileNumber, "This is in the file"
                CLOSE #FileNumber

                FileNumber = FileOpen("MYFILE.FIL", "I", Yes, 0)
                INPUT #FileNumber, DataFromFile$
                CLOSE #FileNumber
  Door Source 4.0
  Programmer's Manual - Page 80

        GameInfoUpdate

        Purpose: To write to the 25 line of the game line of the status line

        Syntax: CALL GameInfoUpdate(Text$, Send.Enter, ColorFore, ColorBack)

        Remarks: If you want a game status line, you should use this routine
        to update line 25 (which will be the game status line). It works
        just like the PRINT command would work with a few differences.
        The Send.Enter really doesn't advance to the next line, but resets
        the column pointer (GameInfoCol) to 1. If you want to start printing
        someplace other than where you are, just set GameInfoCol to the
        column number. See the Advanced Programming section for a detailed
        explanation of how this command works.

        WARNING: You HAVE to use the DSGAME.INT in your main module instead
        of DOORSORC.INT otherwise this routine will not work!

        Parameters Passed:
                Text$ - String to be displayed on line 25

                Send.Enter - Reset GameInfoCol to 1 after displaying
                             (1 = Yes  0 = No)

                ColorFore - Foreground color to use

                ColorBack - Background color to use

        Parameters Returned: None

        Example:
                Text$ = "This is on the game status line!"
                CALL GameInfoUpdate(Text$, No, 0, 7)
  Door Source 4.0
  Programmer's Manual - Page 81

        GetTime

        Purpose: To separate the time into hours, minutes, and seconds

        Syntax: CALL GetTime(Hours, Minutes, Seconds, SinceMid#)

        Remarks: This will take the current time and return it to you
        in a separated form.

        Parameters Passed: None

        Parameters Returned:
                Hours - The hour

                Minutes - The minute

                Seconds - The second

                SinceMid# - The number of seconds since midnight

        Example:
                CALL GetTime(Hours, Minutes, Seconds, SinceMid#)
                CALL Send("Its "+STR$(Hours)+" o'clock", No, Yes, 10)

        See Also: TimeConvert


  Door Source 4.0
  Programmer's Manual - Page 82

        HighScores

        Purpose: To make a high score bulletin

        Syntax: CALL HighScores(Score, HighScoreFile$, OutputNumber)

        Remarks: This will take the user's score and use the high score data
        file specified, update the information, and then either display a
        bulletin or save it to disk. The high score data file, if
        non-existent will be created, its a random access file and can't
        be read/modified in a text editor. Compression can be done with the
        compression utility included with the Door Source archive. You
        will need to open the file for output before calling this routine
        if you want to direct the output to a file, this also allows you
        to create a header (on screen or in the file) for your bulletin.
        The format of where HighScores places the information is like this:

<--21 spaces-------->(NAME OF USER)<---29 spaces--->(SCORE)
                     John Doe                       100
                     Jane Doe                       50

        Parameters Passed:
                Score - Score for user

                HighScoreFile$ - Name of the random access data file
                                 that HighScores creates

                OutputNumber - The filenumber that output should go to, if
                               0 then output goes to screen

        Parameters Returned: None

        Example:
                ScoreDataFile$ = "MYSCORE.SCO"
                Score = 569
                ScoreBlt = 1
                OPEN "SCORES.BLT" FOR OUTPUT AS #1
                CALL HighScores(Score, ScoreDataFile$, ScoreBlt)
  Door Source 4.0
  Programmer's Manual - Page 83

        Incomm

        Purpose: To receive data from the keyboard and com port

        Syntax: CALL Incomm(Text$, Send.Enter, Max.Characters, Color.To.Use)

        Remarks: This is the basic input routine, it will check the keyboard
        and the remote keyboard for input. There are several variables that
        affect input for this routine, and they are all listed here:
                Protected.Input$ - Incomm will show this character in place of
                                   what is really typed. Setting this to ""
                                   will cause normal display of input

                TabSpace - The string to be displayed will be tabbed to this
                           column

                User.Color - The user's input will be displayed in this color

                Caps - Incomm will covert input to all caps before returning
                       (1 = Yes  0 = No)

                No.Enter.Send - After input is completed, a CR/LF won't be
                                sent (1 = Yes  0 = No)

                EchoKey - Will make input not show up on the screens at all
                          (1 = Yes  0 = No)

                Filter - This will filter out high ascii characters (128+)
                         (1 = Yes  0 = No)

                Table$ - Set this to the only keys you want to be accepted
                         if you want to limit the user to a few keys. Set it
                         to Default.Table$ to restore it to normal.

                BackGroundColor - This is the background color for the
                                  prompt and input.

        Parameters Passed:
                Text$ - String to be sent as a prompt

                Send.Enter - Send a CR/LF AFTER the prompt and BEFORE input
                             (1 = Yes  0 = No)

                Max.Characters - The maximum number of character to accept
                                 Setting this to a -1 (or Hockey) will make
                                 Incomm take the first character it gets and
                                 not wait for ENTER to be pressed before
                                 returning.
                                 (0 = No limit  -1 = Hockey  < 1 = Limit)

                Color.To.Use - Foreground color of prompt  Door Source 4.0
  Programmer's Manual - Page 84

        Parameters Returned:
                ARG$ - The input received

        Example:
                ' You don't need to reset all of these variables each
                ' time you call incomm, they are show here just so you
                ' can see how they work.
                Caps = Yes                      ' Turn input to all caps
                Protected.Input$ = "*"          ' Show * instead of letters
                Table$="ABCDEFGHIJKLMNOPQRSTUVWXYZ"  ' Only accept A-Z
                Text$="Enter your name:"
                CALL Incomm(Text$, No, No, 10)
                Protected.Input$ = ""           ' Show what is typed
                CALL Incomm(Text$, No, 25, 10)  ' Limit to 25 characters

        See Also: CommInkey$  Door Source 4.0
  Programmer's Manual - Page 85

        MenuManager

        Purpose: To make a scroll bar menu

        Syntax: CALL MenuManager(Menu$(), Center, TextClr, Bars, SlctClr,
                BarFore, BarBack, BarSelected)

        Remarks: This will create a nice selectable menu with a scroll bar
        for ANSI users to scroll up and down. Non-ANSI users will see the
        menu, but will be forced to just enter a number and will have no
        scroll bar. You shouldn't have more than 20 selections on the menu,
        and all should be numbered. This routine is affected by several
        variables which are:
                Up.Key$ - The key to move the bar up
                          (Default to +)

                Down.Key$ - The key to move the bar down
                            (Default to -)

                ANSI.Select$ - Selection string displayed for ANSI users

                NonANSI.Select$ - Selection string displayed for NON-ANSI users

        Parameters Passed:
                Menu$() - An array with all the menu selections in it

                Center - Center the selections while displaying

                TextClr - Color for selections

                Bars - Number of selections in array

                SlctClr - Color for ANSI.Select$ or NonANSI.Select$ string

                BarFore - Foreground color for scroll bar

                BarBack - Background color for scroll bar

        Parameters Returned:
                BarSelected - The bar selected by the user

        Example:
                See MENUDEMO.BAS included with Door Source


  Door Source 4.0
  Programmer's Manual - Page 86

        MoveCursor

        Purpose: To position the cursor on the screen

        Syntax: CALL MoveCursor(X, Y)

        Remarks: Call this routine to position the cursor anywhere on the
        screen in the upper 22/23 lines (depending on if there is a game
        status line). This routine will not move the cursor if the user is
        not in ANSI mode.

        Parameters Passed:
                X - The row (vertical)

                Y - The column (horizontal)

        Parameters Returned: None

        Example:
                CALL MoveCursor(10, 10)


  Door Source 4.0
  Programmer's Manual - Page 87

        Parser

        Purpose: To separate data in a string with a delimiter

        Syntax: CALL Parser(SearchFor$, SearchIn$, ParArray$(), ErrCode)

        Remarks: This will take a string and look for the character specified
        and store the data in the array, it then repeats this process over
        and over until the end of the string has been reached. This can be
        handy to store numbers in a compact form for storage in a file.

        Parameters Passed:
                SearchFor$ - The string (delimiter) to search for

                SearchIn$ - The string to search in and to parse

        Parameters Returned:
                ParArray$() - Contains the data from SearchIn$ but separated

                ErrCode - Will greater than 1 is a error occurred

        Example:
                SearchFor$ = "*"
                SearchIn$ = "100*200*300*400*500*"
                CALL Parser(SearchFor$, SearchIn$, ParArray$(), ErrCode)
                FOR X = 1 TO 5
                   CALL Send(ParArray$(X), No, Yes, 10)
                NEXT
                ' This would output:
                ' 100
                ' 200
                ' 300
                ' 400
                ' 500
  Door Source 4.0
  Programmer's Manual - Page 88

        NL

        Purpose: To send the specified number of times a CR/LF sequence

        Syntax: CALL NL(Number.Of.Times)

        Remarks: This will send a CR/LF sequence the number of times you
        tell it to. This is base routine for all routines to advance to
        the next line.

        Parameters Passed:
                Number.Of.Times - The number of times to display the CR/LF
                                  sequence.

        Parameters Returned: None

        Example:
                CALL NL(3)              ' Print 3 CR/LF sequences

        See Also: Send
  Door Source 4.0
  Programmer's Manual - Page 89

        PromptIncomm

        Purpose: To provide a very formatted input field with a prompt

        Syntax: CALL PromptIncomm(Text$, Default$, DefaultColor, MaxLength,
                Color.To.Use)

        Remarks: This will make a little ( ) area for input to be inside of
        for ANSI users, non-ANSI users will just have a regular prompt. This
        routine also allows to easily add a "default" to the prompt.

        Parameters Passed:
                Text$ - Prompt to display

                Default$ - "Default" field. Some predefined ones are:
                           Default1 = (Enter=no)
                           Default2 = (Enter=none)
                           Default3 = (Enter=quits)

                DefaultColor - Foreground color for default text

                MaxLength - Maximum number of characters (Required to be
                            greater than 0)

                Color.To.Use - Foreground color for prompt

        Parameters Returned:
                ARG$ - The input received

        Example:
                See PRMTDEMO.BAS

                Text$ = "Enter your name"
                CALL PromptIncomm(Text$, Default3, 15, 10, 11)
                IF AllTrun$(ARG$) = "" THEN
                   ' Process default
                ELSE
                   ' Process other
                END IF
                ' This would output
                ' Enter your name (Enter=quits) ? (         )
                ' The input would be displayed inside the ( )

        See Also: EntryIncomm, Incomm
  Door Source 4.0
  Programmer's Manual - Page 90

        QSend

        Purpose: To send a string local and remote quickly without the
        extra bells and whistles of Send.

        Syntax: CALL QSend(Text$, Send.Enter)

        Remarks: QSend is a very basic sending routine that simply sends
        the given string to the local and remote screens. @X and other
        substitution codes are the only form of color control in the
        strings passed. Extra variables and parameters that affect Send
        don't affect QSend.

        Parameters Passed:
                Text$ - The string to be sent

                Send.Enter - Send a CR/LF after sending is complete
                             (1 = Yes  0 = No)

        Parameters Returned: None

        Example:
                Text$ = "This will be displayed in the last color used."
                CALL QSend(Text$, Yes)

        See Also: BlockSend, ColorEasy, RainbowSend, Send, QSend

  Door Source 4.0
  Programmer's Manual - Page 91

        RainbowSend

        Purpose: To display text in a color, rainbow like form

        Syntax: CALL RainbowSend(Text$, Bell, Enter, Color.To.Use)

        Remarks: This is a creative way to display text to both displays.
        It will take the color given to use, and rotate through the colors
        making a very colorful display. Experiment with different colors
        to find the most desirable effect.

        Parameters Passed:
                Text$ - Text to be displayed

                Bell - Sound the remote speaker, and local is page bell is on

                Enter - Send a CR/LF sequence once displaying is done

                Color.To.Use - Foreground color to display text in

        Parameters Returned: None

        Example:
                Text$ = "This will be displayed"
                CALL RainbowSend(Text$, No, Yes, 10)

        See Also: BlockSend, ColorEasy, Send, QSend
  Door Source 4.0
  Programmer's Manual - Page 92

        RandNum

        Purpose: To generate a random number within a specified range

        Syntax: Number = RandNum(Low, High)

        Remarks: This is handy to generate a random number in the range
        that you need it. It will generate a completely random number.

        Parameters Passed:
                Low - The lowest number desired

                High - The highest number desired

        Parameters Returned:
                Number - The random number generated

        Example:
                CALL Send("The number is "+STR$(RandNum(10,20)), No, Yes, 10)


  Door Source 4.0
  Programmer's Manual - Page 93

        ReadUsers

        Purpose: To read from the PCBoard 14.x users file

        Syntax: CALL ReadUsers(ErrCode)

        Remarks: This will read the user's record from the PCBoard user file
        specified in the global variable UserFile$. The data will be read into
        the global type declaration UserBlock (Which is shown in Appendix D -
        Variable Reference). For other bbs types, most of the data is loaded
        directly from the bbs interface file, and calling a routine to read
        the users file is not necessary. The best way to set UserFile$ is
        to add on another line to the configuration file and read it in
        yourself after the first call to ClrScrn.

        Parameters Passed: None

        Parameters Returned:
                ErrCode - This is the error code is a error occurred
                          1 - Users file not found
                          2 - Wrong BBS type
                          3 - UserFile$ not set to Drive/Path/Filename of users
                              file

        Example:
                See BLCKDEMO.BAS

                ' UserFile$ already set earlier in the program
                CALL ReadUsers(ErrCode)
                CALL Send("You're from "+STR$(UserBlock.CityState), No,Yes,10)

        See Also: WriteUsers
  Door Source 4.0
  Programmer's Manual - Page 94

        Send

        Purpose: To display a string to local and remote screens

        Syntax: CALL Send(Text$, Send.Bell, Send.Enter, Color.To.Use)

        Remarks: This is the basic sending routine and it will display
        to the local and remote screens. This routine will accept @X codes
        and other substitution codes and display the proper things in
        response to it. A few variables affect this routine's output, here's
        a list:
                BackGroundColor - Background color to be used

                TabSpace - The text will be tabbed to this column for display

        Parameters Passed:
                Text$ - The string to be displayed

                Send.Bell - Will sound the speaker on the remote and will
                            also sound the local ONLY if the page bell is on.
                            (1 = Yes  0 = No)

                Send.Enter - Send a CR/LF sequence once displaying is done
                             (1 = Yes  0 = No)

                Color.To.Use - Foreground color to display in

        Parameters Returned: None

        Example:
                Text$ = "This will be displayed!"
                CALL Send(Text$, No, Yes, 10)

        See Also: BlockSend, ColorEasy, RainbowSend, QSend, WindowPrint
  Door Source 4.0
  Programmer's Manual - Page 95

        ShellToDOS

        Purpose: To efficiently shell to DOS in order to avoid conflicts

        Syntax: CALL ShellToDOS(Shell.String$)

        Remarks: This will let Door Source completely wrap up all of its
        operations (actually close the com port, but uphold DTR and carrier)
        so that shelling to a external file transfer program is possible
        without a conflict of interrupts. This command duplicates what
        a SHELL command would do in BASIC, but gives Door Source a chance
        to clean up itself.

        Parameters Passed:
                Shell.String$ - This is the command to be executed once the
                                shell is started

        Parameters Returned: None

        Example:
                Shell.String$ = "DIR >OUTPUT.TXT"
                CALL ShellToDOS(Shell.String$)
  Door Source 4.0
  Programmer's Manual - Page 96

        Sorter

        Purpose: To sort numbers into descending order

        Syntax: CALL Sorter(ParArray$(), Number.To.Sort)

        Remarks: If you need to sort numbers parsed with parser, or other
        numbers in a STRING array, then call this routine and it will
        sort it into a descending order.

        Parameters Passed:
                ParArray$() - The array of numbers to be sorted

                Number.To.Sort - The number of array elements to sort

        Parameters Returned:
                ParArray$() - The sorted array

        Example:
                ParArray$(1) = "400"
                ParArray$(2) = "200"
                ParArray$(3) = "600"
                CALL Sorter(ParArray$(), 3)
                FOR X=1 TO 3
                   CALL Send(ParArray$(X), No, Yes, 10)
                NEXT X
                ' Output would be this:
                ' 600
                ' 400
                ' 200

  Door Source 4.0
  Programmer's Manual - Page 97

        SysopPage

        Purpose: To page the sysop if the page bell is on

        Syntax: CALL SysopPage(Answered)

        Remarks: This routine will check the page bell, and if on, will
        page the sysop using the paging sounds. If the page wasn't answered
        or the sysop isn't around then it will return a 0 in the parameter.
        This routine is affect by several global variables, which are:
                PageSound.1 - Sound #1 to be in the "beep" sound of the page

                PageSound.2 - Sound #2 to be in the "beep" sound of the page

                PageSound.3 - Sound #3 to be in the "beep" sound of the page

                Page.String$ - String to show while paging the sysop

                Not.Around$ - String to show when the sysop is not around

        Parameters Passed: None

        Parameters Returned:
                Answered - If the page was answered
                           (1 = Yes  0 = No)

        Example:
                CALL SysopPage(Answered)

  Door Source 4.0
  Programmer's Manual - Page 98

        TimeConvert

        Purpose: To convert from two variables into the HH:MM format

        Syntax: CALL TimeConvert(Hours, Minutes, NewTime$)

        Remarks: This will combine hours and minutes into the HH:MM format.

        Parameters Passed:
                Hours - The hour

                Minutes - The minute

        Parameters Returned:
                NewTime$ - The hour and minute in HH:MM format

        Example:
                Hours = 10
                Minutes = 30
                CALL TimeConvert(Hours, Minutes, NewTime$)
                CALL Send(NewTime$+" is the next event time.", No, Yes, 10)

        See Also: GetTime


  Door Source 4.0
  Programmer's Manual - Page 99

        ViewFile

        Purpose: To display a file to the local and remote screens

        Syntax: CALL ViewFile(FileName$, ANSICheck, MorePrompts, ExitPrompt)

        Remarks: This will display a ANSI or non-ANSI screen to both screens.
        If you specify to check for a ANSI version of the file, then Door
        Source will take the filename given, add a G to it, and look for
        the existence of that file for ANSI users. You can enable more
        prompts for documentation, or leave them off for long ANSI screens.
        The exit prompt is a "Press [ANY KEY] to continue" prompt that
        is display at the end of the file if told to do so. The user can
        abort the screen at any point by pressing the space bar, CTRL-X, or
        CTRL-K. If the No.Abort global variable is set to 1 (Yes) then
        the user can't abort the display. ANSI files should NOT exceed
        80 characters in length per line.

        Parameters Passed:
                FileName$ - Drive/Path/Filename of file to display

                ANSICheck - Check for ANSI version of file for ANSI users
                            (1 = Yes  0 = No)

                MorePrompts - Display more prompts every 23 lines
                              (1 = Yes  0 = No)

                ExitPrompts - Displays a "Press [ANY KEY]" prompt at end of
                              display (1 = Yes  0 = No)

        Parameters Returned: None

        Example:
                FileName$ = "MYFILE"
                CALL ViewFile(FileName$, Yes, No, Yes)
                FileName$ = "MYDOCS.DOC"
                CALL ViewFile(FileName$, No, Yes, Yes)
  Door Source 4.0
  Programmer's Manual - Page 100

        WaitASec

        Purpose: To delay the program the specified number of seconds

        Syntax: CALL WaitASec(Number.Of.Seconds)

        Remarks: Using the SLEEP command, or a FOR loop to delay a program
        isn't often a good idea in a door because the user could drop carrier.
        This routine will delay the program correctly for the number of
        seconds specified and will also keep track of the carrier signal.

        Parameters Passed:
                Number.Of.Seconds - Number of seconds to delay program

        Parameters Returned: None

        Example:
                CALL WaitASec(5)        ' delay 5 seconds

  Door Source 4.0
  Programmer's Manual - Page 102

        WindowInput

        Purpose: To display a prompt and get input from inside a window

        Syntax: CALL WindowInput(Text$, MaxLength, Row, Col, Fore, Back)

        Remarks: This works just like the Incomm routine, but does the
        I/O inside of a window created with the Windows routine. The
        MaxLength should be just right so that input won't overflow the
        window border and cause problems with erasing it.

        Parameters Passed:
                Text$ - Prompt to be displayed

                MaxLength - Maximum number of characters allowed in input

                Row - Row to display at (horizontal)

                Col - Column to display at (vertical)

                Fore - Foreground color to display prompt in

                Back - Background color to display prompt in

        Parameters Returned:
                ARG$ - The input received

        Example:
                Text$ = "Enter your name:"
                MaxLength = 25: Row = 13: Col = 12
                Fore = 15: Back = 1
                CALL WindowInput(Text$, MaxLength, Row, Col, Fore, Back)

        See Also: Windows, WindowPrint
  Door Source 4.0
  Programmer's Manual - Page 102

        WindowPrint

        Purpose: To display text inside of a window

        Syntax: CALL WindowPrint(Text$, Row, Col, Fore, Back)

        Remarks: This is an easy way of displaying text anywhere inside of
        a window made with the Windows routine. It can also be used for
        quick short displays that aren't at the current cursor location.

        Parameters Passed:
                Text$ - Text to be displayed

                Row - Row to display at (horizontal)

                Col - Column to display at (vertical)

                Fore - Foreground color to display with

                Back - Background color to display with

        Parameters Returned: None

        Example:
                Text$ = "This will be displayed"
                Row = 12: Col = 12: Fore = 15: Back = 1
                CALL WindowPrint(Text$, Row, Col, Fore, Back)

        See Also: Windows, WindowInput
  Door Source 4.0
  Programmer's Manual - Page 103

        Windows

        Purpose: To draw window on the local and remote screens

        Syntax: CALL Windows(ULR, ULC, LRR, LRC, Fore, Back, Border, Shadow)

        Remarks: This will draw a border enclosed area on the screen, and
        will even make a shadow if requested. Printing and input is done
        inside the window with WindowPrint and WindowInput. This is a
        ANSI only routine, and shouldn't be used with non-ANSI users.

        Parameters Passed:
                ULR - Upper Lefthand row

                ULC - Upper Lefthand column

                LRR - Lower Righthand row

                LRC - Lower Righthand column

                Fore - Foreground color to use for border

                Back - Background color to use for border and to fill inside

                Border - The border number
                         1 - Single line
                         2 - Double line
                         3 - Double horizontal, Single vertical
                         4 - Single horizontal, Double vertical

                Shadow - Makes a shadow on the window
                         (1 = Yes  0 = No)

        Parameters Returned: None

        Example:
                ULR = 10: ULC = 10
                LRR = 20: LRC = 70
                CALL Windows(ULR, ULC, LRR, LRC, 11, 1, 4, Yes)

        See Also: WindowInput, WindowPrint
  Door Source 4.0
  Programmer's Manual - Page 104

        WriteUsers

        Purpose: To write to PCBoard 14.x user file

        Syntax: CALL WriteUsers(ErrCode)

        Remarks: This will write the user's record to the PCBoard user file
        specified in the global variable UserFile$. The data written will be
        from the global type declaration UserBlock (Which is shown in Appendix
        D - Variable Reference). For other bbs types, most of the data is
        written when ExitDoor is called, and calling a routine to write to
        the users file is not necessary. The best way to set UserFile$ is
        to add on another line to the configuration file and read it in
        yourself after the first call to ClrScrn.

        Parameters Passed: None

        Parameters Returned:
                ErrCode - This is the error code is a error occurred
                          1 - Users file not found
                          2 - Wrong BBS type
                          3 - UserFile$ not set to Drive/Path/Filename of users
                              file

        Example:
                See BLCKDEMO.BAS

                ' UserFile$ already set earlier in the program
               UserBlock.CityState = "Anytown, USA"
               CALL ReadUsers(ErrCode)

        See Also: ReadUsers

                ░▒▓                                      ▓▒░
                ░▒▓ End of Door Source 4.0 Documentation ▓▒░
                ░▒▓                                      ▓▒░

                         Door Source - Version 4.0
                      Copyrighted 1989,1989,1990,1991
                              By Todd Miller

  Door Source 4.0
  Programmer's Manual - Page 2

  Table of Contents

  Introduction

  The deal on NO registration

  Some Never Nevers

  Quick Start
     Loading Door Source
     First few lines
     Testing your door

  Getting Started

  Command line options

  Door Writing Techniques

  Finishing your door

  Getting more out of Door Source

  Advanced Techniques

  How a door works

  Converting from 3.2 or before

  Summary of new features

  Appendix A - CALL Syntax

  Appendix B - Optimizing your door

  Appendix C - Common Questions

  Appendix D - Variable Reference

  Appendix E - Script Commands

  Appendix F - Command Reference

  Door Source 4.0
  Programmer's Manual - Page 3

        Introduction
        ------------
           Welcome to Door Source! Door Source is a Quick Basic library,
    intended for using with versions 4.0 and above. Door Source provides
    you with a collect of routines to help you interface with a bulletin
    board and the communications port to make a "door", or otherwise
    referred to as a third party program, that adds onto the board.
           Some people don't like having to read a large manual, and rather
    jump right in with both feet and start off, if you would like to quickly
    start, please read the following two sections after this introduction.
    It is advised however, that you read Door Writing Techniques, and
    Getting More out of Door Source too. If you have previously used
    Door Source, you should refer to Converting from 3.2 or before and
    also to the Summary of New Features. Door Source will also be
    referred to as DS in this manual.
           Door Source is provided to you free of charge, and you can
    receive technical support at [phone] (DATA 2400 max).
    Door Source users will be given free access to the other nodes
    after first calling the number above.

        Files included
        --------------
           Here is a list of files that you should have:

                DS40    .QLB - Door Source 4.0 quick library
                DS40    .LIB - Door Source 4.0 link library
                DS40    .DOC - Door Source 4.0 documentation
                DOORSORC.INT - Door Source 4.0 include file
                DSGAME  .INT - Door Source 4.0 include file
                WINDDEMO.BAS - Window demo using the Window routine
                MENUDEMO.BAS - Menu demo using the MenuManager routine
                PRMTDEMO.BAS - Prompts demo using various input routines
                BLCKDEMO.BAS - A demo using the UserBlock type declaration
                ERRDEMO .BAS - A demo with the CarrierLossError variable
                SAMPLE  .BAS - A sample door program writting in Door Source
                MANUAL  .FRM - A form to order a printed manual with disks
                LOADQB  .BAT - A batch file to make loading DS easier
                ????????.DS4 - These are special files with extra routines
                               (DS40.QLB and DS40.LIB already have all of
                                these in them)
                MAKEDS  .EXE - This will help you select the right object
                               files for the most compact DS library.
  Door Source 4.0
  Programmer's Manual - Page 4

        The deal on NO registration
        ---------------------------
           This may seem extremely odd, but Door Source is offered 100%
        completely free. There are no registration fees, no more forms,
        you don't ever have to send us a thing!
           Why? Many years ago when Door Source was first started on,
        I realized the need for a better product in the field of door
        tool kits, and I decided that I would try to fill that gap, but
        at no charge. All the other door kits (that I know of) ask for
        some kind of registration, and I think this is truly one of the
        first that requires none at all.
           But I do like to know who is using Door Source, and a call to
        PC-Technologies just to say thanks, or, better yet, to give a
        suggestion for improvements, is always appreciated! If you have
        a specific need for a routine or improvement to the Door Source
        library, you can call and tell it to me, and you're guaranteed
        that 90% of all improvements or suggestions are added within a
        few releases!

  Door Source 4.0
  Programmer's Manual - Page 5

        Some Never Nevers
        -----------------
           There are some things you never should do when using Door Source.
        What you shouldn't do is listed below, and since most people won't
        believe it unless they know why, we have included reasons, and
        in some cases, alternate routines to use instead.

        Never use CLS, VIEW PRINT, PRINT, LOCATE, or COLOR because
           Door Source handles all screen output, and using these
           will cause Door Source to lose some of its pointers on the
           screen. Also, on systems using DesqView, it could cause lock ups.

        Never use OPEN COM or ON COM, because Door Source doesn't use
           Quick Basic's communication routines, and using these would
           cause a confliction of interrupts between Door Source and
           Quick Basic, that would lead to unpredictable results.

        Never use SCREEN, because Door Source handles screen output,
           it wouldn't be able to follow your change to a different
           mode, and would cause serious problems.

        Never use END or SYSTEM, because that would cause Door Source
           to leave its interrupt handlers still in place and the
           next program to run would probably crash.

        Never use DEFINT, or any of DEF beside DEF FN, because
           Door Source expects variables to be passed that are in
           single precision format (the default of Quick Basic).

        Never use PLAY or SOUND, because it will cause a sound
           when the sysop using your door program may not want sound,
           like in the middle of the night, use BeepSpeaker instead
           of BEEP or SOUND, and AnsiMusic instead of PLAY.

  Door Source 4.0
  Programmer's Manual - Page 6

     Quick Start
     -----------

        Installing and loading Door Source
        ----------------------------------
           After you have unzipped the Door Source file (assuming that you
        have since you're reading this), you will only need to copy a few
        files into your Quick Basic sub-directory. All you will need to
        copy is DS40.QLB, DS40.LIB, and DOORSORC.INT. Now you are ready
        to load up Quick Basic, which you can do by typing:

           QB [your program name] /L DS40

           You also can add on a /CMD[command$ string] that would place
        what you put there into COMMAND$ inside Quick Basic. This would
        be used to easily specify your configuration file for the door,
        an example is this:

           QB MYDOOR /L DS40 /CMDTESTDOOR.CFG LOCAL

           Putting a space in between the /CMD and TESTDOOR.CFG will
        cause Door Source not to recognize your configuration file
        properly.

        The First Few Lines
        -------------------
           Once inside the Quick Basic environment, ready to write a
        new door program, the first line should always be:

        ' $INCLUDE:'DOORSORC.INT'

           This will tell Quick Basic to include this file into your
        program. What this file contains is declarations for the
        Door Source routines (to help eliminate errors), a COMMON SHARED
        block, along with a few CONSTant declarations. At the end of the
        file, it calls the InitDoor routine, which starts Door Source
        rolling. The next line after that in your program should be:

        PROGNAME$ = "My Door"

           You should replace "My Door" with the name of your door. But
        make sure that it is in quotations, or Quick Basic will give you
        a Type mismatch error. The name placed in this string shouldn't
        exceed 20 characters. The next line should be:

        RELEASE$ = "1.0"

           This is the release number (or version number) of your door
        program. It should be less than 6 characters long, and can contain
        letters and numbers (A-Z, a-z, 0-9), as well as punctuation.

  Door Source 4.0
  Programmer's Manual - Page 7

        CALL ClrScrn

           CALL ClrScrn should be the next line in your program. It will
        clear the screen, and now you almost ready to go on about your
        door, however, there is one last thing. In the DOORSORC.INT, when
        it calls InitDoor, it will leave a file open for you (file number 1)
        and this file is the configuration file. If you would like to
        INPUT anything from it, do that here, and once you are done inputing
        anything else that was added onto the configuration file, or if
        you didn't input anything at all, you will need to add one last
        line, which is:

        CLOSE #1

           Now you are ready to write your door. A few basic routines that
        you should look up are Send (on page XX), Incomm (on page XX),
        ClrScrn (on page XX), and NL (on page XX). I'm sure you are
        sick of reading this manual by now, but these are the 4 most
        basic commands. You should also read Testing Your Door before you
        try to run the door for the first time, because there are a few
        things to make sure that you have in your program, and on your
        disk in order for it to work.
  Door Source 4.0
  Programmer's Manual - Page 8

        Getting Started
        ---------------

        Writing a simple program in Door Source
        ---------------------------------------
           Before loading Quick Basic, make sure that you have set the
        proper environment strings to direct Quick Basic to your Door
        Source directory (if you have one).
           You will also need to make a configuration file that you
        can use to test a simple door with. The Door Source configuration
        file format is a simple four line file. You can make it longer
        if your door needs information from it (see Advanced Techniques).
        An example configuration file might be called TESTDOOR.CFG and look
        like this:

        C:\PCB\PCBOARD.SYS
        PC-Technologies
        Todd
        Miller

           The first line is a drive/path/filename to the bbs interface file,
        and the second line is the name of the bbs using the door. The third
        line is the first name of the sysop and the fourth line is the last
        name of the sysop.
           Now, load up Quick Basic, with the /L (library) switch on it like
        this:

        QB /L DS40

           That will load up Quick Basic and the Door Source library. Two other
        switches that you might use when loading Quick Basic are:

        /RUN             - This is put at the beginning of the line right after
                           QB and will make Quick Basic run the file specified.
        /CMDMYCONFIG.CFG - The /CMD option always comes at the end, and what
                           comes DIRECTLY after the /CMD will be loaded into
                           the COMMAND$, this simulates what you would have
                           if someone loaded your program like this:
                           MYDOOR MYCONFIG.CFG
                           The MYCONFIG.CFG would be put in the COMMAND$, but
                           if you want to test doors inside Quick Basic, you
                           should use this option, or set the COMMAND$ from
                           the Run menu in Quick Basic.

           Once Quick Basic is loaded, you should press ALT-R to get the
        Run menu, and the select Modify COMMAND$ (If it isn't listed, then
        go to the options menu and select Full Menus, then try again). Now
        enter in the name of the configuration file that you made earlier
        before loading (If you didn't make it, you can shell to dos from the
        File menu and make it there). Put after the configuration filename,

  Door Source 4.0
  Programmer's Manual - Page 2

        the word LOCAL. LOCAL will tell Door Source to read the configuration
        file, but not to use the BBS interface file. Door Source will prompt
        you for a name, and if you want to use ANSI graphics. This way, you
        don't have to worry about making a test PCBOARD.SYS, DORINFO1.DEF,
        CALLINFO.BBS, or DOOR.SYS. If you didn't specify LOCAL, it would look
        for the bbs interface file that you gave it.
           Now type the following program into Quick Basic:

        ' $INCLUDE:'DOORSORC.INT'
        PROGNAME$="Hello World"
        RELEASE$="1.0"
        CALL ClrScrn
        CLOSE #1

        CALL Send("Hello World!",No,Yes,10)
        CALL Incomm("How are you today, @FIRST@ ?",No,No,14)
        CALL ExitDoor

           Press the F5 key and the program will run. If you receive an
        error, refer to Common Questions to find a solution. You should
        see Door Source ask you for a name, and if you want ANSI graphics.
        Then the screen will clear and it will say Hello World! in High
        Intensity Green, and the beneath that it will show How are you today,
        with your first name. Enter in anything you want and press enter.
        It will then say Closing Door... and more. You'll also notice that
        at the bottom of the screen is a status line, and it will be
        discussed later in this section. Now let's find out how this
        program works.
           First, the INCLUDE file has a lot of DECLAREs in it and a
        COMMON SHARED block, it also makes a CALL to the Door Source
        routine InitDoor. Inside InitDoor, Door Source will read the
        configuration file, process the bbs interface file (in this
        case, it will ask you for your name and if you want ANSI
        instead), and it will set up the communications port if it
        is going to be used.
           In the next two lines, you set up two variables. PROGNAME$
        should be the name of your program. RELEASE$ should be the
        version number of your program. Door Source will display these
        on the status line. PROGNAME$ shouldn't be bigger than 20 characters
        and RELEASE$ shouldn't be bigger than 5 characters. They both
        can contain A-Z, a-z, 0-9, and punctuation.
           Then you make a call to the Door Source routine ClrScrn, which
        clears the screen (local and remote), and updates the status line.
        At this point, if you had added onto the configuration file, you
        would read it here, but since we didn't, we just close the file
        that InitDoor left open for us.
  Door Source 4.0
  Programmer's Manual - Page 2

           The first four lines of the program above should be the first
        four lines in all of your doors, except you would replace what
        PROGNAME$ and RELEASE$ with information for your door.
           Send is a Door Source routine that outputs (local and remote)
        a string, and can optionly beep the speaker, and send a enter when
        done. The number is the color number, here's the format for calling
        Send.

        CALL Send("Hello World!", No, Yes, 10)
                   ^              ^   ^    ^
                   |              |   |    Color to use
                   |              |   Send enter when done?
                   |              Beep the speaker when done?
                   What to output

           Incomm is another routine that outputs first and then waits
        for input back. There are many options that you can use with
        Incomm, most which are in global variables, which are covered
        in the reference for it. Here's the way to call Incomm:

        CALL Incomm("How are you today, @FIRST@ ?", No, No, 14)
                     ^                              ^   ^   ^
                     |                              |   |   Color to use
                     |                              |   Limit the length? If
                     |                              |   so, max length.
                     |                              Send enter before input?
                     What to output first

           You may have noticed how @FIRST@ wasn't displayed on the screen,
        but your first name was instead. That's because that when Door Source
        sees one of these, it knows to replace it with what you want instead.
        There is a complete list of these in Appendix D.
           The last call is to ExitDoor, which closes up Door Source files
        and removes the Door Source interrupt handlers. If you use END
        instead of ExitDoor, then the interrupt handlers will remain in
        place, causing the next program to run to crash. ExitDoor will
        also insure that the caller stays connected while he/she is transferred
        back to the bbs.

  Door Source 4.0
  Programmer's Manual - Page 2

        Colors
        ------
           Door Source can support foreground and background colors. There
        are three different ways that you can use and change colors too.
        Here's a color chart:

        #       Name           Hex     Foreground   Background
        0       Black           0          Y            Y
        1       Blue            1          Y            Y
        2       Green           2          Y            Y
        3       Cyan            3          Y            Y
        4       Red             4          Y            Y
        5       Magenta         5          Y            Y
        6       Brown           6          Y            Y
        7       White           7          Y            Y
        8       Gray            8          Y            N
        9       HiBlue          9          Y            N
        10      HiGreen         A          Y            N
        11      HiCyan          B          Y            N
        12      HiRed           C          Y            N
        13      HiMagenta       D          Y            N
        14      Yellow          E          Y            N
        15      HiWhite         F          Y            N

        Way #1 to use color
        -------------------
           CALL Send("Hello!",No,No,12)
           CALL Send("Bye!",No,Yes,10)

           This would output Hello! in high intensity red and on the same
           line it would put Bye! in high intensity green.

        Way #2 to use color
        -------------------
           CALL Send("Hello!",No,Yes,HiRed)
           CALL Send("Bye!",No,Yes,HiGreen)

           This would output the same thing as above, the only difference
           is that it is easier to read.

        Way #3 to use color
        -------------------
           CALL Send("Hello!@X0ABye!",No,Yes,12)

           This would output the same as the first and second way, but
           this one does it with one string. The whole key to this method
           is the @X0A code in the middle. It tells Door Source to change
           colors.

  Door Source 4.0
  Programmer's Manual - Page 2

        Color Code
        ----------
           Here's how to use the special color codes:

                @X0F
                ^^^^
                |||Foreground color
                ||Background color
                |Second part of signal code
                First part of signal code

           You can also change the background color by setting the
           variable BackGroundColor to a color number on the chart
           above that is valid a background color (0-7).

        Command Line Options
        --------------------
           Door Source has numerous command line options in order to provide
        flexibility with most computer systems. Here is a list:

                LOCAL       - Forces Door Source to run in local mode. This
                              is really meant for testing purposes, but it
                              still reads the configuration file, but doesn't
                              read the bbs interface file.
                NETWORK     - Forces file sharing to be active incase you
                              are using something other than SHARE to manage
                              file locking.
                IRQ=n       - Lets you change the IRQ used for the com port
                              specified in the bbs interface file.
                              (See below for more information)
                ADDR=&Hnnnn - Lets you change the address used for the com
                              port specified in the bbs interface file.
                              (See below for more information)
                PS2         - Forces the PS/2 IRQs and addresses if a PS/2
                              isn't detected (Normally it is, but you can't
                              always tell!)
                RBBS        - Forces Door Source into RBBS/QBBS mode
                WILDCAT     - Forces Door Source into Wildcat 2.0 mode
                DOORSYS     - Forces Door Source into 31-Line DOOR.SYS mode
                PCB121      - Forces Door Source into PCBoard 11.8/12.x mode
                              with COM 1 active
                PCB122      - Forces Door Source into PCBoard 11.8/12.x mode
                              with COM 2 active
                PCB14       - (DEFAULT) Forces Door Source into PCBoard 14.x
                              mode

  Door Source 4.0
  Programmer's Manual - Page 2

        When you use the IRQ or the ADDR option, you must include the other.
        You can't use just the IRQ and not the ADDR, and you can't use just
        the ADDR and not the IRQ. Here's a chart with the STANDARD IRQs
        and addresses for the PS/2s and IBM PCs:
                                Non PS/2
                Com port       IRQ     Address
                   1             4       &H3F8
                   2             3       &H2F8
                   3             4       &H3E8
                   4             3       &H2E8
                  5-8            4       &H3F8

                                PS/2
                Com port       IRQ     Address
                   1             4       &H3F8
                   2             3       &H2F8
                   3             3       &H3220
                   4             3       &H3228
                   5             3       &H4220
                   6             3       &H4228
                   7             3       &H5220
                   8             3       &H5228

  Door Source 4.0
  Programmer's Manual - Page 2

        Door Writing Techniques
        -----------------------
           When writing a door, you should keep three concepts in mind, they
        are:

        1) Compatibility
        2) Flexibility
        3) Multi-node

           A compatible door is a door that easily runs on several bbs types.
        Door Source currently supports PCBoard 11.8+, PCBoard 14.x, WildCat,
        RBBS/QBBS DORINFO1.DEF, and the 31-line version of DOOR.SYS. Modifying
        specific detailed parts of the user's information makes the door
        less portable, since not all systems have the same information as
        others.
           A flexible door is one that allows the sysop to EASILY tell the
        game where things are, and to set the options that they want.
        Options like a tournament mode, turns per day, plays per day, etc,...
        are good options to have. Letting the sysop define text from the
        door is stretching this a little, but some sysops like this feature.
        Of course it does mean a lot of work on your part too.
           A multi-node door is often the hardest to write, but not if you
        know how. Really it is very easy, easier than most think. You first
        have to decide how multi-node you want your door to get. For example,
        you might not won't to try to program something to let two players
        on at the same time attack each other, so maybe you don't let on
        go into the same sector as another that is currently on, or you
        could go for the more complex way and do a one-on-one active battle
        mode (which players would like). But the one thing all multi-node
        doors must do is to share files correctly, and the way to do this
        is to open files as SHARED, and to LOCK and UNLOCK individual records.
        You will also want to keep in contact with other nodes playing
        your door at the same time, and this can be done with a simple file
        that would be organized by node. It would tell the other nodes if
        it was running maintenance (so the others would play while it was), or
        to tell the other nodes where someone is. In the Door Source Door
        tool kit, it contains routines to maintain a file, and others to
        help make your door more multinode. A multi-node door is always
        praised by the sysops of a multi-node system.

        Quick Basic problems
        --------------------
           Quick Basic does have a few problems, and you will encounter them
        if you are working on a large door project. You will probably
        encounter a "Out of Stack Space" or a "Out of Data Space" error.
        I've found that exiting to DOS and then coming back will usually
        solve the problem. If not, then its time to do some work on your
        program. If you know that you're door will be large, or if your
        door gets larger than you expected, then here are a few tips on
        how to get rid of these problems, or to prevent them:

  Door Source 4.0
  Programmer's Manual - Page 2

                1) Use variables, not constants. When you call a routine,
                   like Send, and pass it a constant, the space that the
                   constant used is not released for other programs to use.
                   Instead, it stays in memory until your program quits.
                   So call Send or other routines this way, by defining your
                   variable first.

                        Lin$="Hello!":ColorToUse=10
                        CALL Send(Lin$, No, Yes, ColorToUse)

                   If you didn't set up the variables before hand, you
                   would have just used up 12 bytes of stack space that
                   wouldn't be made available for other things. (I didn't
                   miscount, a string has a 4 byte discriptor on it.)

                2) Use MAKEDS so that your Door Source library will be
                   as small as possible, and so it won't take up extra
                   space with routines you don't need.

                3) Use as few variables as possible. You should set aside
                   two or three variables for your loops, a few for input,
                   and a few for output, etc,... Just don't go around
                   putting in new variables, because it will eliminate
                   stack space.

                4) If you are using your own COMMON SHARED block, eliminate
                   all unnecessary variables from it, and don't declare
                   a function or subroutine as STATIC unless necessary.

        Large doors
        -----------
           When writing LARGE doors with Door Source, you should use
        a multi-module program. To create a new module, you must select
        the Create file option from the file menu (full menus only).
        Here are some tips for writing large doors:

                1) Make a COMMON SHARED block for each of your modules
                   that has commonly used variables.

                2) Include the DOORSORC.INT at the beginning of each module
                   so that it can use the Door Source routines and variables.

                3) Make as many things as possible a routine or a function,
                   and place those routines and functions into a module of
                   their own (You could even have several modules of routines).

                4) Remember that you can't GOTO or GOSUB to a line number or a
                   label in another module.

  Door Source 4.0
  Programmer's Manual - Page 2

                5) Anything that is done more than once is a good candidate for
                   routine or function, even if it just calculates a score
                   or shows lots of information.

                6) When calling routines (Door Source or your own), pass
                   variables, not constants to them.

  Door Source 4.0
  Programmer's Manual - Page 2

        Gathering Data from the User
        ----------------------------
           When writing your door, you will want to keep a consistent, but
        friendly and easy to use approach to receiving information back from
        the user. Using the PromptIncomm or EntryIncomm is a good way to
        gather a limited amount of data, PromptIncomm is most useful for
        yes and no questions, and for amounts. EntryIncomm is good for
        long replies (sentences, names, etc,...).
           You can also vary Incomm in a number of ways, the Incomm routine
        is the kernel for PromptIncomm and EntryIncomm. You can write your own
        routine to first do your special prompt and then call Incomm. For
        example, if you wanted to make a prompt that used RainbowSend so the
        prompt is lots of different colors, you could do this:

        SUB RainbowInput(Text$, LimitField)
           CALL RainbowSend(Text$, No, No, 11)
           CALL Incomm("", No, LimitField, Last.Clr.Used)
        END SUB

           This would be output Text$ (the prompt) using RainbowSend first,
        then use Incomm to receive the data. The variable, Last.Clr.Used, is
        a Door Source variable that has the number of the last color used
        stored in it.
           If you have specific keys that you want the user to use and to
        lock out the others, use the Table$ and Default.Table$ to limit
        the input to certain keys, for example:

           Table$="YN"
           CALL Incomm("Do you want to quit (Y/N) ? ", No, 1, 14)
           Table$=Default.Table$

           The above example first sets Table$ to equal YN, now Door Source
        will only allow the user to input the letters Y and N (Lower case
        will NOT work, you have to add in the lower case letters too!).
        The last line sets Table$ back to the default (when Door Source
        starts, Table$ is already at the default). This is very important
        so that you don't accidentally keep limiting input when you don't
        want to. Also, NEVER change Default.Table$, doing so will make it
        only harder on you to undo the Table$ setting. You don't have to
        worry about adding in characters like backspace or enter, because
        Door Source assumes that you will want to let the user use those
        keys. Table$ does not affect any output routines, only the Door
        Source input routines (except CommInkey$ and CommKeyInkey$ functions)

  Door Source 4.0
  Programmer's Manual - Page 2

        Making friendly menus
        ---------------------
           Friendly menus (to you and the user) are menus that can be
        aborted in the middle of display. To make a friendly menu in
        Door Source, define a array and put your menu in it. This also
        makes it easy for you to make a quick change to one or all of
        your menus if you have all of the arrays in the same place.
        An example of how to make a friendly menu would be:

        CONST Main.Menu.Length = 5

        DIM Main.Menu$(5)

        Main.Menu$(1)="(1) Quit"
        Main.Menu$(2)="(2) Quit"
        Main.Menu$(3)="(3) Quit"
        Main.Menu$(4)="(4) Quit"
        Main.Menu$(5)="(5) Quit"

        CALL BlockSend(Main.Menu$(), No, Main.Menu.Length)

           If the user was to press the space bar, CTRL-X, or CTRL-K while
        the menu was displaying, it would stop displaying and let your
        program go on to receive the input.
           Another form of the friendly menu (but doesn't allow aborting)
        is using MenuManager to display your menu, and allows ANSI users to
        use a scroll bar to scroll up and down and make their choice, and
        allows non-ANSI users to enter their selection.

        Presenting information in a compact format
        ------------------------------------------
           Displaying ten, twenty character long lines, on ten separate lines
        is a waste of space. Instead, you could compact the display to five
        lines, or even less. Setting TabSpace in between calls to one of the
        Send routines will let you make a nicely formatted display, for example:

           CALL Send("Info #1:"+Info1$, No, No, 10)
           TabSpace = 40
           CALL Send("Info #2:"+Info2$, No, Yes, 10)
           CALL Send("Info #3:"+Info3$, No, No, 10)
           TabSpace = 40
           CALL Send("Info #4:"+Info4$, No, Yes, 10)

        Would look like:

        Info #1: Something                      Info #2: Something else
        Info #3: Anything                       Info #4: Anything else!

  Door Source 4.0
  Programmer's Manual - Page 2

           If you want to display information from an array in a compact
        format, you could do this:

           Stack = 0
           FOR X = 1 TO 10
              IF Stack = 0 THEN
                 CALL Send("Info :"+Info$(X), No, No, 10)
                 TabSpace = 40
                 Stack = 1
              ELSE
                 CALL Send("Info :"+Info$(X), No, Yes, 10)
                 Stack = 0
              END IF
           NEXT X
           IF TabSpace = 40 THEN TabSpace = 0

           In the above example, the variable Stack changes from 0 to 1 and
        back again to keep track of whether or not it's time to tab over to
        column 40 or to end the line. The IF after the NEXT X makes sure that
        you aren't set at column 40 for your next output when you don't want
        to be.
           You could also put in another IF block inside the FOR loop to let
        you decide whether or not you have any information to display or not.
        You could also modify all the above examples so that you could have
        three columns and not just two.

        The Configuration File
        ----------------------
           You can make the configuration file for your door program larger
        than what Door Source requires it to be, and you can read in the
        information yourself too. Door Source automatically reads in the
        first four lines of the configuration file and sets everything up
        for you to read the rest. Reading more from the configuration file
        is simple:

        ' $INCLUDE:'DOORSORC.INT'
        ProgName$="Configuration Reader"
        Release$="1.0"
        LINE INPUT #1, ExtraInfo$
        LINE INPUT #1, ExtraNumber
        CLOSE #1
        CALL ClrScrn

           Even though there is no open statement, Door Source opened the
        file and read the information from it already (It did this from in
        the DOORSORC.INT). Remember to close the file after use, even if you
        don't use it at all. The only limit to how long your configuration
        file can be is the disk space and the amount of memory you can
        use to store the information. The configuration file can not be
        in a random access format, only sequential.
  Door Source 4.0
  Programmer's Manual - Page 2

        Testing your Door
        -----------------
           The easiest way to test your door is to run it from inside the
        Quick Basic environment. You first have to have three things done
        so that you can, and they are:

                1) Have a sample configuration file in the Quick Basic
                   directory.

                2) Load Quick Basic with the /L option and DS40 after it
                   For example:
                        QB /L DS40 /CMDTESTDOOR.CFG LOCAL

                3) Load Quick Basic with the /CMD option and your configuration
                   file's name after it with the word LOCAL.
                   (See above example)

           If you forgot to load with the /CMD option, you can set it from
        inside Quick Basic from the Run menu (Modify COMMAND$).
           Now all you have to do is press F5 to run your program. If you
        have any problems, refer to Appendix C - Common Questions.

  Door Source 4.0
  Programmer's Manual - Page 2

        Finishing your Door
        -------------------
           To eliminate all possible problems, you should first thoroughly test
        you door in two manners, logically, and unlogically. When you are
        logically testing it, you should use your door the way you designed
        it to be used, noting the little problems as you go. Then when you
        unlogically test it, you try testing your program in a way completely
        opposite of how you designed it. This method is a through method to
        debug your program. You will find most of the errors through this
        method, but then there are always situations that even you didn't
        think of in either of these manners.
           To finish a door you will need to compile to door into a EXE format.
        This way you can use the door without having to load QuickBasic to run
        your doors. Since Door Source doesn't use Quick Basic's communications
        routines, you CAN compile your door to be a stand-alone program, that
        doesn't need BRUN45.EXE. If you prefer to not make it a stand-alone,
        you do not have to use a patched version of BRUN45.EXE like other
        door packages require.
           In order to compile your program, you must go to the Run menu and
        select Make EXE. It will compile your program in memory and then
        a window will pop up asking what you want the final file name of the
        program to be, and other options. Do not select the produce debug
        code option, it will only make your program larger and slower, and
        allow people to break it in the middle by pressing CTRL-Break. After
        you have everything like you want it, select one of the button on the
        bottom of the window to start the process.
           Of course, you'll need to provide some documentation for your
        door, and good documentation should have some of these sections listed
        here:
                Table of contents
                Disclaimer
                Overview/Summary of the door
                List of files in archive
                Configuration file setup
                Command line options
                Batch file setup
                Customization instructions
                List of function/ALT keys
                Possible errors/Troubleshooting

           A good disclaimer is always something that is hard to come by, here
        is a disclaimer that pretty much covers you:

                This program and other files associated with it are not
                guaranteed to be bug free or virus free. We are not
                responsible for any damages of any kind, including
                profit loses and data loss, that relate directly or
                indirectly to these programs and files. You may
                distribute this program, as long as it is in unmodified
                form with all the files originally included.

  Door Source 4.0
  Programmer's Manual - Page 2

           You may wish to add/change/delete something from this one, but it
        is a pretty good one. A overview or summary of the door would be a
        simple explanation of exactly what your door does, no specifics
        really. The configuration file section should show a sample
        configuration file, and give a sentence or two on each line in the
        file. The command line options should show the user how to
        configure the door to run with his system. Refer to the chapter
        on command line options to put into your documentation.
           The batch file setup should show a few example batch files, and
        telling you if you need to add it in your daily event, etc,...
        The customization section should tell the sysop that uses your door
        how to better customize it to what he needs. Some examples might be
        aliases allowed/not allowed, location of files, prompts, etc,...
           The list of function keys is basically this:

                  F3  - Printer toggle
                  F4  - Page bell toggle
                  F5  - Shell to DOS
                  F7  - Caller alarm toggle
                  F8  - Return caller to board
                  F10 - Start sysop chat
                  ESC - Enter sysop chat
                ALT-X - Drop to DOS after caller logs off
                ALT-N - Sysop next on flag

           Troubleshooting should list a few possible errors that might
        occur, and how to solve them. Like if error number 53 (File not found)
        occurs, then search your configuration file for a misspelled filename
        or a wrong path. If error 61 (Disk full) occurs, free up disk space.
        Some errors can't be solved, and you could list those and have them
        call a bulletin board for more help.

  Door Source 4.0
  Programmer's Manual - Page 2

        Getting more out of Door Source
        -------------------------------

        This section and the following section, Advanced Techniques, are
        very closely related. With Door Source 4.0, it is basically possible
        for you to write your own input and output routines using out base
        routines to do the dirty work. The difference in between this section
        and the next is simply that this tells you how to take advantage of
        some of the new variables and features, and the next section tells
        you more on programming more advanced things with Door Source.

        The definable page sound
        ------------------------

           You can easily change the sound of the SysopPage routine by
        setting 3 variables - PageSound.1, PageSound.2, and PageSound.3
        The sound generated is in the order of PageSound.1, then PageSound.2,
        and then the final sound is PageSound.3. The numbers you put in
        PageSound should be in the acceptable range of the SOUND command,
        which is somewhere around 45-32767. A page sound of 200, 400, 600
        would make a sound that starts out low, then the next sound is
        about double the pitch of the first, and the third is double the
        pitch of the second. Its possible to create a variety of different
        sounds with this, try experimenting with the SOUND command first to
        find what you like the best. The duration of the sounds is set, and
        can't be changed.
                Example:
                PageSound.1=200
                PageSound.2=400
                PageSound.3=600
                CALL SysopPage(Answered)

        Filtering your input
        --------------------

           Sometimes, you may want to limit the input to a question to a
        few letters, or selectively not recognize certain characters. To
        do so, you should set the Table$ variable. An example would be:
                Example:
                Table$ = "YNyn"
                CALL Incomm("You can only type Y and N:",No,1,15)
                ' Anything else besides Y,N,y,n that the user types is
                ' not displayed or recognized. Backspace and enter CAN NOT
                ' be filtered out.
                Table$ = Default.Table$
                ' This is necessary to reset the filter back to normal,
                ' if you didn't do this then you'll have problems with
                ' later Incomm commands still being restricted with the
                ' filtering.
                Output:
                You can only type Y and N:Y  Door Source 4.0
  Programmer's Manual - Page 2

        Protecting input from prying eyes
        ---------------------------------

           When a password or something secret needs to be concealed, you
        can now set a "substitution character" that will be displayed in
        place of what the user really types. You can make the character
        anything you wish, but making it a null turns it off.
                Example:
                Protected.Input$="*" ' Now shows a * in place of text
                CALL Incomm("Password:", No, No, 15)
                Protected.Input$=""  ' Turns it off - Back to normal display
                Output:
                Password:******

        Two fancier input prompts
        -------------------------

           EntryIncomm
           -----------
           EntryIncomm prints out a field of (----) above the area where
           the user's input will be displayed. The size of the field is based
           on how big you make the field. Good for ANSI and NON-ANSI!
                Example:
                CALL EntryIncomm("Your new name:", 25, LightGreen, Yellow)
                '                                  ^ Field size
                Output:
                             (-------------------------)
                Your new name:Zantigahicatal

           PromptIncomm
           ------------
           PromptIncomm is most useful in ANSI cases, but will handle
           non-ansi well too, but the purpose of the routine is defeated
           then. What it does is create a field similar to the EntryIncomm
           but the field is on the same line as the input. The second text
           field is the "default field" tells the user what it defaults to
           if they press enter, but its up to you to interpret them pressing
           enter. You can pass a string as the second parameter, and it
           will use that instead of one of the already programmed constants.
           The constants are:
                Default1 = (Enter=no)
                Default2 = (Enter=none)
                Default3 = (Enter=quits)

                Example:
                CALL PromptIncomm("Do you wish to quit",Default1,
                        LightGreen, 1, Yellow)
                '                   ^ Field size
                Output:
                Do you wish to quit (Enter=no) ? (N)

  Door Source 4.0
  Programmer's Manual - Page 2

           Unabortable ViewFiles
           ---------------------
           Do you want to force the user to see out an entire file? Its easy
           to block the abort codes by setting the variable No.Abort to YES,
           then when the user tries to abort, it won't let him. However, if
           more prompts are still offered, answering NO to it will stop the
           display.
                Example:
                No.Abort = YES
                CALL ViewFile("MYFILE.ANS", No, No, No)
                No.Abort = NO   ' Reset it back to normal

           Disabling carrier checking
           --------------------------
           How would you like to turn off carrier checking for a
           call back verification program of some sort, or something
           along those lines? Try setting Carrier.Check to YES, and
           Door Source will *IGNORE* the carrier detect flag. If the
           user drops carrier, you'll have to handle and detect yourself!
                Example:
                Carrier.Check = No  ' Disables carrier checking
                Carrier.Check = Yes ' (Default) enables carrier checking

           Checking the baud and the carrier, setting DTR, CTS, and RTS
           ------------------------------------------------------------

              Checking the baud rate
              ----------------------
              The variable Baud& has the baud rate stored in it. Here's
              what the number in it means:
                        1       - Local mode
                        300     - 300 baud
                        1200    - 1200 baud
                        2400    - 2400 baud
                        4800    - 4800 baud
                        9600    - 9600 baud
                        -192    - 19,200 baud
                        -384    - 38,400 baud
                        -1152   - 115,200 baud

              Checking the carrier
              --------------------
              The routine CheckCarrier will tell you if a carrier is
              present.
                Example:
                CALL CheckCarrier(CarrierFlag)
                IF CarrierFlag = NO AND Baud& > 1 THEN
                   CALL ExitDoor  ' Carrier lost!
                END IF

  Door Source 4.0
  Programmer's Manual - Page 2

              Setting the DTR, CTS, and RTS
              -----------------------------

                DTR
                ---
                The DTR (Data Terminal Ready) when on normally means that
                you are on-line, and have a connection. However, on most
                modems, turning it off while it is on will break the
                connection.
                        Example:
                        CALL ChangeDTR(YES)   ' Turn DTR on
                        CALL ChangeDTR(NO)    ' Turn DTR off

                CTS Control On/Off
                ------------------
                CTS (Clear To Send) is used to signal the other modem that
                it is ok to send characters. Modems that don't preform
                error checking or UARTS that don't have buffers may require
                CTS flow-control to be on during high-speed file transfers.
                        Example:
                        CALL ChangeCTS(YES)   ' Turn CTS control on
                        CALL ChangeCTS(NO)    ' Turn CTS control off

                RTS
                ---
                RTS (Request To Send) is used by most auto-dial modems to
                see if a computer is ready to receive data from the modem.
                If the RTS signal isn't detected, some modems may refuse
                to accept modem commands or send result codes.
                        Example:
                        CALL ChangeRTS(YES)   ' Turn RTS on
                        CALL ChangeRTS(NO)    ' Turn RTS off

           Automatic more prompts
           ----------------------
           If you're displaying lots of information, like programmed in
           documentation, and you don't want to keep track of when you
           need to show a more prompt or a press any key prompt, just
           simply set the AutoMore variable to one of the settings:
                0                              Disables the prompts (default)
                MorePrompt    (Or the value 1) Causes automatic more prompts
                PressKeyPromp (Or the value 2) Causes automatic press any key
                Example:
                    AutoMore = MorePrompt
           The variable Lines.Since will tell you how many lines have been
           sent SINCE the last ClrScrn WITH one of the Send routines or
           Incomm routines. The automatic prompts are by default not
           enabled, and when enabled, they occur every 23 lines.

  Door Source 4.0
  Programmer's Manual - Page 2

        Advanced Techniques
        -------------------
           Door Source has several new features that are more program
        related, that are just a little bit to hard to put in the previous
        section, Getting more out of Door Source.

           The extra line status line
           --------------------------
           Normally, Door Source has lines 24 and 25 in use with its status
           line, but if you have some information of you're own that you'd
           like to put on it, now you can by using the GameInfoUpdate
           routine with the variable GameInfoCol.
           The only major change you have to make to your program is to use
           the DSGAME.INT file instead of the DOORSORC.INT file, and you'll
           need to write a routine to do the status line updating.
           First of all, the Door Source status line is moved up to lines
           23 and 24, and we leave 25 for your use. You call the
           GameInfoUpdate routine like you would call print, for example:
                ' $INCLUDE:'DSGAME.INT'
                  .
                  .  (Later in the program)                         Background
                  .                                                     \/
                CALL GameInfoUpdate("This is on the 25th line!", No, 14, 7)
                                     ^ Text                      ^   ^
                                                                 |   Foreground
                                                                 Enter
           The background is the last number, and the color you specify is
           the foreground color. The enter parameter is like the ; on a
           print command, telling it no keeps the current position at that
           spot, but yes will start at column 1 when you do the next
           GameInfoUpdate.
           But what if you want to position the cursor somewhere on the
           line without printing to that location? Or what if you want
           to know where the cursor is? You can tell both of these by
           looking at the GameInfoCol variable. For example:
                A = GameInfoCol   ' A now contains the horizontal position
                                  ' of the cursor on line 25.
                GameInfoCol = 30  ' With the next GameInfoUpdate call, it
                                  ' will start printing at column 30.
           Now the only thing missing is your interfacing this into your
           program. The easiest way to do this is to write a new ClrScrn
           routine, that you call in place of ClrScrn, this is necessary
           because ClrScrn doesn't update your line when called, so you'll
           have to do it. Here's an example of a new ClrScrn:
              SUB ClearTheScreen
                 CALL ClrScrn
                 CALL GameInfoUpdate("This is on the 25th line!",No,14,7)
              END SUB

  Door Source 4.0
  Programmer's Manual - Page 2

           Writing your own output routines
           --------------------------------
              With Door Source, you can virtually write your own output
           routines for use with your program. The kernel for all of our
           output routines is the Send1Line routine. It will send one
           line out to the local and remote display, and will decode the
           substitution codes too! All that's left for you to do is to
           write your own routine that calls this routine. For example,
           say you wanted to write a routine that would colorize all of the
           letters that are the capital A, then you might do this:
              SUB ColorizeTheA(Text$,AColor$,RegularColor$)
                 FOR X=1 TO LEN(Text$)
                    IF MID$(Text$,X,1)="A" THEN
                       CALL Send1Line(AColor$+MID$(Text$,X,1))
                    ELSE
                       CALL Send1Line(RegularColor$+MID$(Text$,X,1))
                    END IF
                 NEXT X
              END SUB
           The variables AColor$ and RegularColor$ would store the @X color
           codes for the colors for A's and other letters.

           Writing your own input routines
           -------------------------------
              You can write your own input routines too with Door Source.
           The main kernel for the input routine is CommInkey$, and a few
           other routines supplement the features offered in Incomm. An
           example input routine that is very simple might be:
              SUB GetInput
                 DO
                    A$=CommInkey$
                    IF A$="" THEN A$=INKEY$
                 LOOP UNTIL A$<>""
                 ARG$=A$
              END SUB
           You should also be aware that all filters, and special variables
           that affect input with Incomm do NOT work with CommInkey$, you
           have to program in support for them yourself if you want them.
           The GetInput routine above would wait for a key to be pressed
           on the local or remote keyboard. Now say that you want to echo
           the character to the screen and to the remote screen, you'd do
           this:
              SUB GetInput
                 DO
                    A$=CommInkey$
                    IF A$="" THEN A$=INKEY$
                 LOOP UNTIL A$<>""
                 ARG$=A$
                 CALL Send1Line(A$)   ' Echos the character
              END SUB
  Door Source 4.0
  Programmer's Manual - Page 2

           Now maybe you want to trap the function keys, you could do this:
              SUB GetInput
                 DO
                    A$=CommInkey$
                    IF A$="" THEN A$=INKEY$
                 LOOP UNTIL A$<>""
                 ARG$=A$
                 IF LEFT$(A$,1)=CHR$(0) THEN
                    CALL ExtendedCode(A$,NULL) ' Process the function key
                 ELSE
                    CALL Send1Line(A$)         ' Echos the character
                 END IF
              END SUB
           The NULL variable on the ExtendedCode is used only by Incomm,
           and you shouldn't pass anything to it in place of it, and its
           not used to return anything to your program. Now the GetInput
           routine we have above is pretty good. It will accept input
           from the keyboard and from remote, check for a extended code
           and process it, otherwise it will echo the character.
           You can also write your own chat routine, but use our code
           by calling Incomm with the second parameter as a 5. This
           will print the "Sysop started chat at" and the "Hello, this is"
           lines, and then will handle the input and color for you, then
           once the sysop presses ESC to end the chat, it will print the
           "Sysop ended chat at" and return control to you. So basically, by
           passing a 5 as the second parameter forces a chat.
              Example:
              CALL Incomm("",5,No,15)   ' Forces a chat

           Carrier loss processing
           ----------------------
              Sometimes in more complex doors, its necessary to process
           a carrier drop yourself in order to save and wrap up files.
           You could turn carrier checking off, but its best if you use
           the CarrierLossError method. What you do is set CarrierLossError
           to YES and when carrier is dropped, a error number 255 will be
           forced, and if you have a ON ERROR trapping processing in your
           program, you will be able to catch it, and then let Door Source
           finish off the rest. For an example, please refer to the example
           program ERRDEMO.BAS.

  Door Source 4.0
  Programmer's Manual - Page 2

        How a door works
        ----------------
           Understanding how a door works is good to know so that you can
        better plan your door. Here's a simple diagram on what happens:

                        BBS Creates the interface file and exits
                                         \|/
                                Door's batch file is run
                                         \|/
             |-->      Door loads and reads in the interface file
             |                           \|/
Door Source  |      The door opens the communications port if needed
handles this |                           \|/
with your    |                 User interacts with the door
program      |                           \|/
             |-->  Door eventually exits, updating the interface file
                                         \|/
                       BBS reloads and reads in the interface file
                                         \|/
                              User continues using the bbs

        The DOORSORC.INT file sets up the necessary DECLAREs for the routines
        and the functions, it then sets up the COMMON SHARED block which lets
        you share variables with Door Source, like Baud&. Then it sets up
        a few constants, and then calls InitDoor, then the Door Source library
        takes over, and reads the configuration file, initialize its variables
        and then opens the com port for access. Then control is returned to
        you and your program picks up from their setting the program's name
        and version, etc,... While you're doing other processing, Door Source
        is ALWAYS looking at the com port, keeping received data in its
        buffer until you're ready for it. Door Source monitors everything
        for you, from carrier detection to characters being sent to
        characters being received, all behind the scenes.

  Door Source 4.0
  Programmer's Manual - Page 2

        Converting from Door Source 3.2 or before to 4.0
        ------------------------------------------------
           There are a few changes in how you call routines from 3.2 and
        before. Here's the list and how to change your program to fit 4.0
        without major restructuring. The easiest way to change things is
        using the QuickBasic search and replace feature from the edit menu.

         * Routine AllTrun is now a function, you use it like this:
                A$ = AllTrun$(A$)
         * Routine HighScores has a extra parameter. The new third parameter
           lets you output its output to a already open file by passing the
           file number, but if you pass a 0, it outputs to the screen.
                CALL HighScores(Score, ScoreDataFile$, OutputFileNumber)
         * Routine Windows has a few parameters changes, the text foreground
           and text background have been deleted since WindowPrint and
           WindowInput do all window processing. Windows in your program
           will need to be re-written because of this.
                CALL Windows(ULR, ULC, LRR, LRC, Foreground, Background,
                        Border, Shadow)
         * Routine Windows has two new borders, they are:
                3 - Double horizontal Single vertical
                4 - Single horizontal Double vertical

         * Routine DayOfWeek moved into ScriptCMD.
                I1$="DAYOFWEEK":CALL ScriptCMD
         * Routine MenuManager parameters have been changed, the Select$
           parameter has been deleted, since now ANSI.Select$ and
           NonANSI.Select$ (COMMON SHARED variables) are now used for the
           select string. BarForeground and BarBack have been added, they
           have the foreground and background color for the selection bar.
                CALL MenuManager(Menu$(),Center,TextColor,NumberOfSelections,
                   BarForeground, BarBackground, BarnumberSelected)
         * Routine SysopPage now has an extra parameter, this extra one is
           used to return a variable in, not to pass one. It returns a 1 (YES)
           if the page was answered.
                CALL SysopPage(Answered)
         * Routine ErrorLevelSet has been removed because of environment
           conflicts.

  Door Source 4.0
  Programmer's Manual - Page 2

        Summary of new features
        -----------------------
                LOCAL command line switch added
                NETWORK command line switch added
                Up.Key$ and Down.Key$ variables added
                SysopPage changed
                PageSound.1, PageSound.2, and PageSound.3 added
                Page.String$ added
                F5 (Shell to DOS) added
                F3 (Printer toggle) added
                GameInfoUpdate routine added
                GameInfoCol added
                Table$ and Default.Table$ added
                PromptIncomm routine added
                No.Abort added
                MenuManager changed
                Parser changed
                WindowPrint and WindowInput routines added
                ExtendedCode routine added
                Protected.Input$ added
                BlockSend routine added
                RainbowSend routine added
                Windows routine changed
                DayOfWeek routine moved into ScriptCMD
                RandNum function fixed
                EntryIncomm added
                AllTrun routine changed into a function
                CheckCarrier routine added
                Baud& variable added
                CarrierLossError added
                Carrier.Check added
                ChangeDTR, ChangeCTS, and ChangeRTS added
                IRQ command line parameter added
                ADDR command line parameter added
                PS2 command line parameter added
                HighScores changed
                ALL ROUTINES optimized to run faster, and to be more compact

  Door Source 4.0
  Programmer's Manual - Page 2

        Appendix A - CALL Syntax
        ------------------------

        CALL QSend(Text$, Enter)
        CALL BackSpace(Text$)
        CALL ExtendedCode(Text$,NULL)
        CALL BeepSpeaker()
        CALL NL(Number.Of.Lines)
        CALL Send(Text$, Bell, Enter, Color.To.Use)
        CALL Incomm(Text$, Enter, Limit.Field, Color.To.Use)
        CALL ANSIMusic(Music$, Music)
        CALL GameInfoUpdate(Text$, Enter, Color.To.Use, Color.Background)
        CALL BackSpaceOver()
        CALL Center(Text$)
        CALL ClrScrn
        CALL ColorEasy(Text$, Color.To.Use, Enter)
        CALL DoorBusy()
        CALL ErrorLevelSet(Error.Level)
        CALL ExitDoor()
        CALL GetTime(Hours, Minutes, Seconds, SinceMid#)
        CALL HighScores(Score, Score.FileName$, OutputFileNumber)
        CALL MenuManager(Menu$(), Center, TextColor, Number.Of.Bars,
           Select.Color, BarForeground, BarBackground, BarSelected)
        CALL MoveCursor(X,Y)
        CALL Parser(SearchFor$, SearchIn$, Array$(), ErrCode)
        CALL ReadUsers(ErrCode)
        CALL ScriptCMD()
        CALL Sorter(Array$(), How.Many.Elements)
        CALL SysopPage(Answered)
        CALL TimeConvert(Hours, Minutes, New.Time$)
        CALL ViewFile(FileName$, Check.For.GFile, MorePrompts, EnterPrompt)
        CALL WaitASec(How.Many.Seconds.To.Wait)
        CALL Windows(ULR, ULC, LRR, LRC, Fore, Back, Border, Shadow)
        CALL WriteUsers(ErrCode)
        CALL BlockSend(Array$(), Center, Lines.To.Send)
        CALL WindowPrint(Text$, Row, Col, Fore, Back)
        CALL WindowInput(Text$, MaxLength, Row, Col, Fore, Back)
        CALL RainbowSend(Text$, Bell, Enter, Color.To.Use)
        CALL PromptIncomm(Text$, Default$, DefaultColor, LimitField,
           Color.To.Use)
        CALL EntryIncomm(Text$, LimitField, FieldColor, Color.To.Use)
        CALL ShellToDos(Shell.String$)

  Door Source 4.0
  Programmer's Manual - Page 2

        Appendix B - Optimizing your door
        ---------------------------------
           The best way to optimize a door program can be divided into two
        parts.
                1) The first part is cleaning up your code. This would mean
                   elimination of most or all GOTOs and GOSUBs, elimination
                   of as many constants as possible, and elimination of
                   repetition in your code.
                2) The second part is compiling from the command line.
                   QuickBasic compiles with some unneeded options when you
                   select the Make EXE command from the Run menu. You might
                   need the error trapping flag (/X) if you have a ON ERROR
                   statement in your program, and you might need the switch
                   for dynamic arrays (/AH) if you're using them. Here's a
                   sample compilation for a NON-STANDALONE program:
                      BC MYPROG;
                      LINK /EX MYPROG.BAS,MYPROG.EXE,,BRUN45.LIB+DOORSORC.LIB

                   For a STANDALONE program, use this:
                      BC MYPROG/O;
                      LINK /EX MYPROG.BAS,MYPROG.EXE,,BCOM45.LIB+DOORSORC.LIB

                   These parameters will compile the to the most compact
                   format. You can also use PKLITE to compress it more.

  Door Source 4.0
  Programmer's Manual - Page 2

        Appendix C - Common Questions
        -----------------------------
        Q: How do I read in additional information from the configuration
           file?
        A: To read in more information, simply INPUT from file #1 after you
           call ClrScrn for the first time. Make sure to close it when you're
           done. Here's an example:
              ' $INCLUDE:'DOORSORC.INT'
              PROGNAME$="Example"
              RELEASE$="1.0"
              CALL ClrScrn
              INPUT #1, ExtraInfo
              CLOSE #1
           Door Source doesn't read past the fourth line of the configuration
           file, so you can put whatever you please there.
        Q: How do I test a door from inside QuickBasic?
        A: You must have first loaded QuickBasic with the /L option specifying
           the Door Source library. For example:
              QB MYDOOR /L DOORSORC
           Then you will need to setup the command line parameters by setting
           the COMMAND$, you do this from the Run menu from Modify COMMAND$.
           Now, as long as your configuration file, bbs interface file, and
           all other files you need exist, you can press F5 and test your door
           from QuickBasic.
        Q: Should I compile as a stand-alone door?
        A: It's up to you. A stand-alone door will not need the BRUN45.EXE,
           but it will make your door significantly larger, and compiling
           not as a stand-alone will save space. Door Source will work fine
           either way.
        Q: What does the error "Error opening port -1" mean?
        A: It means that you have specified a invalid serial port, and you
           should check your bbs interface file or your bbs's setup.

  Door Source 4.0
  Programmer's Manual - Page 2

        Appendix D - Variable Reference
        -------------------------------
        The first part of this reference is of the global variables, the
        second is of the global UserBlock type declaration.

        Variable Name   Purpose
        -------------   ------------------------------------------------------
        ARG$            Input from user, returned by Incomm routine
        SYSDPATH$       Drive/Path/Filename of bbs interface file
        BBSName$        Name of BBS running on
        SysopNM$        Sysop FULL name
        CALLNAME$       Caller's FULL name
        Baud&           Baud rate of caller
        PROGNAME$       Name of your door
        RELEASE$        Version of your door
        ANSI            Ansi Flag  (1 = On  0 = Off)
        I1$,I2$,I3$     Input variables to script commands
        O1$,O2$,O3$     Output variables from script commands
        User.Color      Color that user input will be display in
        BackGroundColor Color to use for background when displaying
        Exit.Dor.1$     First line of ExitDoor message
        Exit.Dor.2$     Second line of ExitDoor message
        Exit.Dor.Clr1   Color of first line
        Exit.Dor.Clr2   Color of second line
        UserF$          First name of caller
        UserL$          Last name of caller
        Caps            Convert all input to caps (1 = Yes  0 = No)
        Page.Bell       Page bell toggle (-1 = On  0 = Off)
        Caller.Alarm    Caller alarm (-1 = On  0 = Off)
        Sysop.Next      Sysop next on toggle (-1 = On  0 = Off)
        Hang.Up         Exit to DOS after log off toggle (-1 = On  0 = Off)
        User.Record     Record number of user
        Network         Network active (1 = Yes  0 = No)
        Display.Toggle  Display on/off toggle (ignored by DS -1 = On  0 = Off)
        Printer.Toggle  Printer on/off (-1 = On  0 = Off)
        BusyFlag        A signal to ExitDoor that DoorBusy routine is in use
        UserFile$       Drive/Path/Filename of USERS file (PCBoard ONLY!)
        Up.Key$         Key to be used for scrolling up in MenuManager
        Down.Key$       Key to be used for scrolling down in MenuManager
        Parity          Parity of user calling (7 or 8 data bits)
        Filter          Incomm filtering active (filters all high ascii out)
        BusyFile$       Drive/Path/Filename of busy file for DoorBusy routine
        SysFirst$       Sysop's first name
        SysLast$        Sysop's last name
        CommPort        Communacations port being used (1-8)
        Last.Clr.Used   Last color used in a call to Send
        EchoKey         STOPS echoing keys to remote user (1 = Yes  0 = No)
        No.Enter.Send   Incomm doesn't send enter when done (1 = Yes  0 = No)
        File.Missing$   String ViewFile$ displays when file is not found
        BBSType$        Type of BBS in use (PCB14, PCB121, PCB122, WILDCAT,
                        RBBS, or DOORSYS)
  Door Source 4.0
  Programmer's Manual - Page 2

        Node            Node caller is on
        TabSpace        Send will tab to this column before sending
        InverseText     Reverses the text colors (Foreground/Background switch)
        Sysop           Sysop is on (1 = Yes  0 = No)
        BlinkText       Send will make text blink
        Not.Around$     String to show when Sysop doesn't answer page
        PARAM$          Extra command-line parameters that DS didn't use
        Page.String$    String to display while paging
        PageSound.1     First tone of page
        PageSound.2     Second tone of page
        PageSound.3     Third tone of page
        GameInfoCol     Column to start printing on game status line
        Default.Table$  Table containing a unaltered filter
        Table$          Specific filtering of characters for Incomm
        KeyBoardTimeOut Number of SECONDS for a keyboard time out
        Protected.Input$  Incomm displays this instead of what user types
        ANSI.Select$    Menu Manager's ANSI selection string
        NonAnsi.Select$ Menu Manager's NON-ANSI selection string
        Carrier.Check   Disables carrier checking (1 = Yes  0 = No)
        CarrierLossError  Causes ExitDoor to generate a error 255 if carrier
                          is dropped.
        No.Abort        Disables CTRL-X, CTRL-K keys from aborting screens
                        (1 = Yes  0 = No)
        AutoMore        Automatically prints more prompts/press any key prompts
        Lines.Since     Number of lines printed since last more/press prompt


  Door Source 4.0
  Programmer's Manual - Page 2

        This is the reference for the UserBlock global variable

  Variable                Type          P  W  R  D   Description
 -------------------     -----------    -  -  -  -   -------------------------
 CityState            AS STRING * 24    Y  Y  Y  Y   City and state of user
 Password             AS STRING * 12    Y  Y     Y   User's Password
 BusinessPhone        AS STRING * 13    Y        Y   User's Business/Data phone
 VoicePhone           AS STRING * 13    Y  Y     Y   User's Voice/Home phone
 LastDateOn           AS STRING * 20    Y  Y     Y   Last date user was on
 LastTimeOn           AS STRING * 5     Y            Last time user was on
 ExpertMode           AS STRING * 1     Y  Y     Y   Expert mode "Y" or "N"
 ProtocolType         AS STRING * 5     Y  Y     Y   Protocol selected
 LastDirListing       AS STRING * 10    Y  Y         Last date viewed dir
 SecurityLevel        AS INTEGER        Y  Y  Y  Y   Security Level for user
 TimesOn              AS INTEGER        Y  Y     Y   Number of times on before
 PageLength           AS INTEGER        Y  Y         Page length for user
 TotalUploads         AS INTEGER        Y  Y     Y   Total # of uploads made
 TotalDownloads       AS INTEGER        Y  Y     Y   Total # of downloads made
 DailyDownloadBytes   AS DOUBLE         Y            # of download bytes left
 UserComment          AS STRING * 30    Y            User Comment field
 SysopComment         AS STRING * 30    Y            Sysop Comment field
 ElapsedTime          AS INTEGER        Y  Y         Elapsed Time on system  1
 Subscription         AS STRING * 20    Y
 SubscriptionExpire   AS STRING * 20    Y
 AreaRegistration     AS STRING * 50    Y  Y     Y   Areas user has access to
 AreaExpire           AS STRING * 50    Y
 AreasToScan          AS STRING * 50    Y
 TotalDownloadBytes   AS DOUBLE         Y  Y     Y   Total bytes downloaded
 TotalUploadBytes     AS DOUBLE         Y            Total bytes uploaded
 DeleteFlag           AS STRING * 1     Y            Flag to delete user
 TimeEnteredDoor      AS STRING * 5     Y  Y  Y  Y   Time user entered door
 AreaFrom             AS INTEGER        Y        Y   Area user exited from
 MemorizedMessage     AS LONG           Y            Memorized message #
 TimeCalled           AS STRING * 5     Y  Y         Time user called bbs
 DailyDownloadTotal   AS INTEGER           Y         Total downloads TODAY
 MaxDownloadLimit     AS DOUBLE            Y         Max downloads TODAY
 LastRead             AS INTEGER           Y         Message last read
 MaxDownloadKLimit    AS DOUBLE         Y  Y     Y   Max d/l K TODAY
 ExpirationDate       AS STRING * 10             Y
 LR0                  AS STRING * 4     Y
 LR1                  AS STRING * 4     Y
 LR2                  AS STRING * 4     Y
      .
      .
 LR39                 AS STRING * 4     Y


  Door Source 4.0
  Programmer's Manual - Page 2

        Appendix E - Script Commands Reference
        --------------------------------------
        Script commands are several small routines packed all into one.
        In order to access them, you set the according variables, and
        then make a call to ScriptCMD routine. For example, if you
        wanted to display a Press [ANY KEY] to continue prompt, you
        could do this:
                I1$ = "PRES"
                CALL ScriptCMD
        Variables I1$, I2$, and I3$ are all INPUT variables that store
        information for the routine to use. O1$, O2$, and O3$ are all OUTPUT
        variables that return information from the routine to you.
        I1$ is always the name of the routine you're calling inside of
        ScriptCMD. You only have to specify the first 4 letters of the
        word unless stated in the documentation.


  Door Source 4.0
  Programmer's Manual - Page 2

        LTRIM

        Purpose: To trim all leading spaces

        Name in ScriptCMD: LTRIM

        Remarks: This routine is a simple truncation routine to remove
        all leading spaces from a string.

        Parameters Passed:
                I2$ - The string to be truncated

        Parameters Returned:
                O1$ - The truncated string


  Door Source 4.0
  Programmer's Manual - Page 2

        RTRIM

        Purpose: To trim all trailing spaces

        Name in ScriptCMD: RTRIM

        Remarks: This routine is a simple routine to truncate all trailing
        spaces from a string.

        Parameters Passed:
                I2$ - The string to be truncated

        Parameters Returned:
                O1$ - The truncated string


  Door Source 4.0
  Programmer's Manual - Page 2

        Upper Case

        Purpose: To convert a string to all upper case

        Name in ScriptCMD: UPPER

        Remarks: This routine will convert a string into all upper case

        Parameters Passed:
                I2$ - The string to be converted

        Parameters Returned:
                O1$ - The converted string


  Door Source 4.0
  Programmer's Manual - Page 2

        Lower case

        Purpose: To convert a string to all lower case

        Name in ScriptCMD: LOWER

        Remarks: This routine will convert a string into all lower case

        Parameters Passed:
                I2$ - The string to be converted

        Parameters Returned:
                O1$ - The converted string


  Door Source 4.0
  Programmer's Manual - Page 2

        More Prompt

        Purpose: To display a more prompt

        Name in ScriptCMD: MORE

        Remarks: This will display a more prompt and allow the user to
        select Yes to continue, No to abort, and C to go non-stop. It
        will return a Y (for yes), a N (for no), or a C (for non-stop)
        in O1$

        Parameters Passed: None

        Parameters Returned:
                O1$ - Contains a Y, N, or C


  Door Source 4.0
  Programmer's Manual - Page 2

        Press Any Key

        Purpose: To display a Press [ANY KEY] to continue prompt

        Name inside ScriptCMD: PRESS

        Remarks: This will display a Press [ANY KEY] to continue prompt and
        then wait for the key to be pressed:

        Parameters Passed: None

        Parameters Returned: None


  Door Source 4.0
  Programmer's Manual - Page 2

        Exist

        Purpose: To check if a file exists

        Name inside ScriptCMD: EXIST

        Remarks: This will check for the existence of the file specified.

        Parameters Passed:
                I2$ - Drive/Path/Location of file to check for

        Parameters Returned:
                O1$ - If the file exists
                      (Y = Yes  N = No)


  Door Source 4.0
  Programmer's Manual - Page 2

        Name conversion

        Purpose: To convert a name into proper upper and lower case

        Name inside ScriptCMD: NAMECASE

        Remarks: This will take a name like "DR. JOHN DOE" and properly
        convert it into "Dr John Doe"

        Parameters Passed:
                I2$ - The name to be converted

        Parameters Returned:
                O1$ - The converted name


  Door Source 4.0
  Programmer's Manual - Page 2

        Coding and Decoding

        Purpose: To code and decode a string

        Name inside ScriptCMD: CODER

        Remarks: This is a simple coding routine that will resist causal
        attempts to break it. It will code and decode with the same password.
        The longer the password, the better the protection you will have.
        The password shouldn't have any high ASCII characters in it.

        Parameters Passed:
                I2$ - String to be coded/decode

                I3$ - Password to code/decode with

        Parameters Returned:
                O1$ - The coded/decoded string


  Door Source 4.0
  Programmer's Manual - Page 2

        Reverse Bits

        Purpose: To reverse the bits in a string

        Name inside ScriptCMD: REVERSEBITS (MUST USE ENTIRE NAME!)

        Remarks: This will take all of the characters in a string and reverse
        it's bits. This is a simple, but easy to break coding routine. To
        unreverse the bits, just call the routine again.

        Parameters Passed:
                I2$ - The string to bit reverse

        Parameters Returned:
                O1$ - The bit reversed string


  Door Source 4.0
  Programmer's Manual - Page 2

        Reverse Characters

        Purpose: To reverse the order of characters in a string

        Name inside ScriptCMD: REVERSECHARS (MUST USE ENTIRE NAME!)

        Remarks: This changes the order of characters in a string so that
        the first is last, and the last is first, and so on throughout the
        entire string. To decode it, simply call the routine again.

        Parameters Passed:
                I2$ - The string to be reversed

        Parameters Returned:
                O1$ - The reversed string


  Door Source 4.0
  Programmer's Manual - Page 2

        Appendix F - Command Reference
        ------------------------------

        Each command is shown in a set format. The format is as follows:

        Name of routine

        Purpose: States the prupose of the routine

        Remarks: Tells you the general information on the routine and how
        to use it.

        Parameters Passed: Tells you what parameters to the routine and what
            they are for.

        Parameters Returned: Tells you what parameters are returned and what
            is in them.

        Example: A short little program showing the usage of the routine

        See Also: (on some routines) Gives you a reference to other routines
            that do nearly the same thing or that work with this routine.
        QSend

        Purpose: To send a string local and remote quickly without the
        extra bells and whistles of Send.

        Syntax: CALL QSend(Text$, Send.Enter)

        Remarks: QSend is a very basic sending routine that simply sends
        the given string to the local and remote screens. @X and other
        substitution codes are the only form of color control in the
        strings passed. Extra variables and parameters that affect Send
        don't affect QSend.

        Parameters Passed:
                Text$ - The string to be sent

                Send.Enter - Send a CR/LF after sending is complete
                             (1 = Yes  0 = No)

        Parameters Returned: None

        Example:
                Text$ = "This will be displayed in the last color used."
                CALL QSend(Text$, Yes)

        See Also: BlockSend, ColorEasy, RainbowSend, Send, QSend


        CommKeyInkey$

        Purpose: To get one character from the local or remote keyboard

        Syntax: Character$ = CommKeyInkey$

        Remarks: This will check the local keyboard and the com port buffer
        for keys waiting to be read, if one is found, it will read it and
        return it, otherwise it will return a null. If you want to wait for
        a key to be pressed, you should put this routine in a WHILE loop.

        Parameters Passed: None

        Parameters Returned:
                Character$ - Either null (if no key was pressed local or
                             remote) or a key from the keyboard or com port
                             buffer.

        Example:
                DO
                   Character$ = CommKeyInkey$
                LOOP UNTIL Character$ <> ""

        See Also: Incomm, CommInkey$


        FileOpen

        Purpose: To aid in opening files in a better, easier way

        Syntax: FileNumber = FileOpen(FileName$, Access$, Sharing, Length)

        Remarks: When you want to open a file and you don't know what the
        next available file number is, or you don't want to refer to files
        by their number, or if you don't want to have to fool with checking
        if a network is active every time a file is opened, this routine
        is what you should call. It will find the next available file number
        and open the file according to your specifications and return the
        file number to you in a variable so you can use it in place of a
        number.

        Parameters Passed:
                FileName$ - This is the name of the file to be opened
                Access$ - The method in which you want to open the file
                          for access.
                                I - Sequential Input
                                O - Sequential Output
                                A - Append (Write at end of file)
                                R - Random Read/Write
                                B - Binary Read/Write
                Sharing - Will open files to be shared if specified and a
                          network is active
                          (1 = Yes  0 = No)
                Length - For random and binary files only, this will open
                         the file with this as the record length.

        Parameters Returned:
                FileNumber - This is the variable you'd use for I/O with the
                             file. It will contain a -1 if the file wasn't
                             found that you tried to open only if you're
                             trying to do sequential input.

        Example:
                FileNumber = FileOpen("MYFILE.FIL", "O", Yes, 0)
                PRINT #FileNumber, "This is in the file"
                CLOSE #FileNumber

                FileNumber = FileOpen("MYFILE.FIL", "I", Yes, 0)
                INPUT #FileNumber, DataFromFile$
                CLOSE #FileNumber


        CheckTimeLeft

        Purpose: To tell you how many minutes a user has left on the system

        Syntax: TimeRemaining = CheckTimeLeft

        Remarks: This function will return the number of minutes that the user
        currently on has left for this call. Be careful not to assign the
        value returned to a variable named TimeLeft because doing so will
        modify Door Source's variable and cause the user's time to go berserk!

        Parameters Passed: None

        Parameters Returned:
                TimeRemaining - The number of minutes left the user has

        Example:
                CALL Send("("+STR$(CheckTimeLeft)+" min. left )", No, No, 14)

        See Also: AdjustTimeLimit


        BackSpace

        Purpose: To backspace on the local and remote screen and also erase
        the proper character in the string passed

        Syntax: CALL BackSpace(Text$)

        Remarks: This will allow you to write your own input routines for
        use, and when a user presses the backspace key, call this routine and
        it will send the proper backspacing codes and erase the backspaced
        character from the string passed.

        Parameters Passed:
                Text$ - A string that will the backspace will be preformed on

        Parameters Returned:
                Text$ - The new string with the last character erased

        Example:
                IF KeyPressed$ = CHR$(8) THEN
                   CALL BackSpace(Text$)
                END IF


        ExtendedCode

        Purpose: To let you trap F-keys in your own I/O routines

        Syntax: CALL ExtendedCode(CodeToProcess$, NULL)

        Remarks: If you are writing your own version of Incomm, and would
        like to take advantage of Door Source's F-Key processing routines,
        call this with the key pressed and it will take the necessary
        action, which may be updating the status bar or shelling to DOS.

        Parameters Passed:
                CodeToProcess$ - The two character code of the key pressed

                NULL - This variable shouldn't be used by your routine, it
                is only used by Door Source and is specified only to maintain
                compatibility.

        Parameters Returned: None

        Example:
                A$ = INKEY$
                IF LEN(A$)>1 THEN               ' Extended code
                   CALL ExtendedCode(A$, NULL)
                END IF


        BeepSpeaker

        Purpose: To sound the local and remote speaker

        Syntax: CALL BeepSpeaker

        Remarks: Calling BeepSpeaker instead of sending a bell code to the
        screen and com port is better since it will always beep the remote
        speaker but won't make the local speaker sound unless the page bell
        is on.

        Parameters Passed: None

        Parameters Returned: None

        Example:
                CALL BeepSpeaker


        NL

        Purpose: To send the specified number of times a CR/LF sequence

        Syntax: CALL NL(Number.Of.Times)

        Remarks: This will send a CR/LF sequence the number of times you
        tell it to. This is base routine for all routines to advance to
        the next line.

        Parameters Passed:
                Number.Of.Times - The number of times to display the CR/LF
                                  sequence.

        Parameters Returned: None

        Example:
                CALL NL(3)              ' Print 3 CR/LF sequences

        See Also: Send


        Send

        Purpose: To display a string to local and remote screens

        Syntax: CALL Send(Text$, Send.Bell, Send.Enter, Color.To.Use)

        Remarks: This is the basic sending routine and it will display
        to the local and remote screens. This routine will accept @X codes
        and other substitution codes and display the proper things in
        response to it. A few variables affect this routine's output, here's
        a list:
                BackGroundColor - Background color to be used

                TabSpace - The text will be tabbed to this column for display

        Parameters Passed:
                Text$ - The string to be displayed

                Send.Bell - Will sound the speaker on the remote and will
                            also sound the local ONLY if the page bell is on.
                            (1 = Yes  0 = No)

                Send.Enter - Send a CR/LF sequence once displaying is done
                             (1 = Yes  0 = No)

                Color.To.Use - Foreground color to display in

        Parameters Returned: None

        Example:
                Text$ = "This will be displayed!"
                CALL Send(Text$, No, Yes, 10)

        See Also: BlockSend, ColorEasy, RainbowSend, QSend, WindowPrint


        Incomm

        Purpose: To receive data from the keyboard and com port

        Syntax: CALL Incomm(Text$, Send.Enter, Max.Characters, Color.To.Use)

        Remarks: This is the basic input routine, it will check the keyboard
        and the remote keyboard for input. There are several variables that
        affect input for this routine, and they are all listed here:
                Protected.Input$ - Incomm will show this character in place of
                                   what is really typed. Setting this to ""
                                   will cause normal display of input

                TabSpace - The string to be displayed will be tabbed to this
                           column

                User.Color - The user's input will be displayed in this color

                Caps - Incomm will covert input to all caps before returning
                       (1 = Yes  0 = No)

                No.Enter.Send - After input is completed, a CR/LF won't be
                                sent (1 = Yes  0 = No)

                EchoKey - Will make input not show up on the screens at all
                          (1 = Yes  0 = No)

                Filter - This will filter out high ascii characters (128+)
                         (1 = Yes  0 = No)

                Table$ - Set this to the only keys you want to be accepted
                         if you want to limit the user to a few keys. Set it
                         to Default.Table$ to restore it to normal.

                BackGroundColor - This is the background color for the
                                  prompt and input.

        Parameters Passed:
                Text$ - String to be sent as a prompt

                Send.Enter - Send a CR/LF AFTER the prompt and BEFORE input
                             (1 = Yes  0 = No)

                Max.Characters - The maximum number of character to accept
                                 Setting this to a -1 (or Hockey) will make
                                 Incomm take the first character it gets and
                                 not wait for ENTER to be pressed before
                                 returning.
                                 (0 = No limit  -1 = Hockey  < 1 = Limit)

                Color.To.Use - Foreground color of prompt

        Parameters Returned:
                ARG$ - The input received

        Example:
                ' You don't need to reset all of these variables each
                ' time you call incomm, they are show here just so you
                ' can see how they work.
                Caps = Yes                      ' Turn input to all caps
                Protected.Input$ = "*"          ' Show * instead of letters
                Table$="ABCDEFGHIJKLMNOPQRSTUVWXYZ"  ' Only accept A-Z
                Text$="Enter your name:"
                CALL Incomm(Text$, No, No, 10)
                Protected.Input$ = ""           ' Show what is typed
                CALL Incomm(Text$, No, 25, 10)  ' Limit to 25 characters


        See Also: CommInkey$


        AllTrun$

        Purpose: To truncate all leading and trailing spaces from a string

        Syntax: Text$ = AllTrun$(Text$)

        Remarks: This will remove all of those leading and trailing spaces
        that are a result of random file input, use of STR$, and other
        functions of BASIC.

        Parameters Passed:
                Text$ - The string to remove leading and trailing spaces from

        Parameters Returned:
                Text$ - The string without leading and trailing spaces

        Example:
                Text$ = "   These extra spaces will be removed   "
                Text$ = AllTrun$(Text$)


        ANSIMusic

        Purpose: To play ANSI music to those users who can use it

        Syntax: CALL ANSIMusic(Music$, Music)

        Remarks: Some communacations programs can support and play ANSI music
        but not all of them. Qmodem, for example, will play ANSI music. You
        should ask your users near the beginning of the program "Do you have
        ANSI music?" and if they answer yes, then set Music to Yes (1)
        otherwise set it to No (0). You don't have to use Music, but whatever
        variable you store that value in should always be the second parameter
        of the call to this routine. The music string can be anything that
        the BASIC command PLAY would be able to play. The local speaker
        won't play the music unless the page bell is on.

        Parameters Passed:
                Music$ - The music to be played

                Music - If the user supports ANSI music or not
                        (1 = Yes  0 = No)

        Parameters Returned: None

        Example:
                Music = Yes
                Music$ = "ABCDEFG"
                CALL ANSIMusic(Music$, Music)


        GameInfoUpdate

        Purpose: To write to the 25 line of the game line of the status line

        Syntax: CALL GameInfoUpdate(Text$, Send.Enter, ColorFore, ColorBack)

        Remarks: If you want a game status line, you should use this routine
        to update line 25 (which will be the game status line). It works
        just like the PRINT command would work with a few differences.
        The Send.Enter really doesn't advance to the next line, but resets
        the column pointer (GameInfoCol) to 1. If you want to start printing
        someplace other than where you are, just set GameInfoCol to the
        column number. See the Advanced Programming section for a detailed
        explanation of how this command works.

        WARNING: You HAVE to use the DSGAME.INT in your main module instead
        of DOORSORC.INT otherwise this routine will not work!

        Parameters Passed:
                Text$ - String to be displayed on line 25

                Send.Enter - Reset GameInfoCol to 1 after displaying
                             (1 = Yes  0 = No)

                ColorFore - Foreground color to use

                ColorBack - Background color to use

        Parameters Returned: None

        Example:
                Text$ = "This is on the game status line!"
                CALL GameInfoUpdate(Text$, No, 0, 7)


        BackSpaceOver

        Purpose: To erase what is already on a line

        Syntax: CALL BackSpaceOver

        Remarks: This routine will backspace over everything to column 1,
        erasing everything on that line. If you have a prompt that you'd
        like to erase or something, this is the routine to call to erase
        it.

        Parameters Passed: None

        Parameters Returned: None

        Example:
                CALL BackSpaceOver

        See Also: BackSpaceToCol


        Center

        Purpose: To aid in centering strings for output

        Syntax: CALL Center(Text$)

        Remarks: This will strip out all @X codes and substitute in the
        proper text for substitution codes and will then set TabSpace to
        equal the correct column to make the string look centered. The
        string that you pass is NOT modified by this routine. This routine
        also will NOT print out the results but only set TabSpace.

        Parameters Passed:
                Text$ - The string to be centered

        Parameters Returned: None

        Example:
                Text$ = "This will be centered!"
                CALL Center(Text$)
                CALL Send(Text$, No, Yes, 10)


        ClrScrn

        Purpose: To clear the local and remote screens

        Syntax: CALL ClrScrn

        Remarks: This will effectively clear the screen for both sides
        using the fastest method that the caller can use. Setting
        BackGroundColor previous to calling this routine will cause the
        entire screen to be that color!

        Parameters Passed: None

        Parameters Returned: None

        Example:
                CALL ClrScrn


        ColorEasy

        Purpose: To colorize a string and output it

        Syntax: CALL ColorEasy(Text$, Color.To.Use, Send.Enter)

        Remarks: If you have a string that you'd like to colorize without
        having to bother with multiple calls to Send or with @X codes, then
        use this routine. It will colorize A-Z, a-z, 0-9, and punctuation
        all in different colors. The Color.To.Use that you specify will
        affect the output of color over the whole text, experiment with
        different values to best fit what you need.

        Parameters Passed:
                Text$ - The string to be colorized and displayed

                Color.To.Use - This will vary the output for the different
                               colors used in coloring the text

                Send.Enter - Send a CR/LF sequence once displaying is finished

        Parameters Returned: None

        Example:
                Text$ = "This will be VERY colorful!!"
                CALL ColorEasy(Text$, 10, Yes)

        See Also: BlockSend, RainbowSend, Send, QSend


        DayOfWeek

        Purpose: To calculate the which day of the week it is

        Syntax: Day = DayOfWeek

        Remarks: This routine will return a value from 1 to 7 indicating
        which day of the week it is. A 1 is Sunday, 2 is Monday, and so on.

        Parameters Passed: None

        Parameters Returned:
                Day - A number from 1-7 representing the day of the week

        Example:
                IF DayOfWeek = 1 THEN
                   CALL Send("It's SUNDAY!", No, Yes, 14)
                ELSE
                   CALL Send("It's not sunday!", No, Yes, 10)
                END IF


        DoorBusy

        Purpose: To keep a door from being used by two nodes at once

        Syntax: CALL DoorBusy

        Remarks: If you aren't going to program multi-node support, call
        this routine so that multinode systems won't have problems running
        your door. You have to set the global variable BusyFile$ to the
        drive/path/filename of a "lockout file" that will be the signal
        to other nodes that the door is in use. If another node is using your
        door, then this routine will call DoorBusy and not return control
        to your program.

        Parameters Passed: None

        Parameters Returned: None

        Example:
                BusyFile$ = "MYDOOR.NET"
                CALL DoorBusy


        ExitDoor

        Purpose: To close the com port and update the bbs interface file

        Syntax: CALL ExitDoor

        Remarks: Whenever you want to end your door, you MUST call this
        routine. NEVER let your door simply just come to an end or have the
        END or SYSTEM command in it. This routine will uphold the DTR and
        cleanup Door Source's variables, handlers, etc,... It will also
        update the bbs interface file with the current information. After
        calling this routine, control will not be returned to your door.

        Parameters Passed: None

        Parameters Returned: None

        Example:
                CALL ExitDoor


        FileExist

        Purpose: To detect is a file exists on a disk

        Syntax: Exists = FileExist(FileName$)

        Remarks: If you're opening files or preforming something with files
        you should check, before attempting use, if they exist and not assume
        that they are there, otherwise your program will generate a error
        and most likely crash the board it was running on.

        Parameters Passed:
                FileName$ - Drive/Path/Filename to the file to be checked for

        Parameters Returned:
                Exists - If the file exists or not
                         (-1 = Yes  0 = No)

        Example:
                IF FileExist("MYFILE.FIL") THEN
                   CALL Send("It exists!", No, Yes, 12)
                END IF


        GetTime

        Purpose: To separate the time into hours, minutes, and seconds

        Syntax: CALL GetTime(Hours, Minutes, Seconds, SinceMid#)

        Remarks: This will take the current time and return it to you
        in a separated form.

        Parameters Passed: None

        Parameters Returned:
                Hours - The hour

                Minutes - The minute

                Seconds - The second

                SinceMid# - The number of seconds since midnight

        Example:
                CALL GetTime(Hours, Minutes, Seconds, SinceMid#)
                CALL Send("Its "+STR$(Hours)+" o'clock", No, Yes, 10)

        See Also: TimeConvert


        HighScores

        Purpose: To make a high score bulletin

        Syntax: CALL HighScores(Score, HighScoreFile$, OutputNumber)

        Remarks: This will take the user's score and use the high score data
        file specified, update the information, and then either display a
        bulletin or save it to disk. The high score data file, if
        non-existent will be created, its a random access file and can't
        be read/modified in a text editor. Compression can be done with the
        compression utility included with the Door Source archive. You
        will need to open the file for output before calling this routine
        if you want to direct the output to a file, this also allows you
        to create a header (on screen or in the file) for your bulletin.
        The format of where HighScores places the information is like this:

<--21 spaces-------->(NAME OF USER)<---29 spaces--->(SCORE)
                     John Doe                       100
                     Jane Doe                       50

        Parameters Passed:
                Score - Score for user

                HighScoreFile$ - Name of the random access data file
                                 that HighScores creates

                OutputNumber - The filenumber that output should go to, if
                               0 then output goes to screen

        Parameters Returned: None

        Example:
                ScoreDataFile$ = "MYSCORE.SCO"
                Score = 569
                ScoreBlt = 1
                OPEN "SCORES.BLT" FOR OUTPUT AS #1
                CALL HighScores(Score, ScoreDataFile$, ScoreBlt)


        MenuManager

        Purpose: To make a scroll bar menu

        Syntax: CALL MenuManager(Menu$(), Center, TextClr, Bars, SlctClr,
                BarFore, BarBack, BarSelected)

        Remarks: This will create a nice selectable menu with a scroll bar
        for ANSI users to scroll up and down. Non-ANSI users will see the
        menu, but will be forced to just enter a number and will have no
        scroll bar. You shouldn't have more than 20 selections on the menu,
        and all should be numbered. This routine is affected by several
        variables which are:
                Up.Key$ - The key to move the bar up
                          (Default to +)

                Down.Key$ - The key to move the bar down
                            (Default to -)

                ANSI.Select$ - Selection string displayed for ANSI users

                NonANSI.Select$ - Selection string displayed for NON-ANSI users

        Parameters Passed:
                Menu$() - An array with all the menu selections in it

                Center - Center the selections while displaying

                TextClr - Color for selections

                Bars - Number of selections in array

                SlctClr - Color for ANSI.Select$ or NonANSI.Select$ string

                BarFore - Foreground color for scroll bar

                BarBack - Background color for scroll bar

        Parameters Returned:
                BarSelected - The bar selected by the user

        Example:
                See MENUDEMO.BAS included with Door Source


        MoveCursor

        Purpose: To position the cursor on the screen

        Syntax: CALL MoveCursor(X, Y)

        Remarks: Call this routine to position the cursor anywhere on the
        screen in the upper 22/23 lines (depending on if there is a game
        status line). This routine will not move the cursor if the user is
        not in ANSI mode.

        Parameters Passed:
                X - The row (vertical)

                Y - The column (horizontal)

        Parameters Returned: None

        Example:
                CALL MoveCursor(10, 10)


        Parser

        Purpose: To separate data in a string with a delimiter

        Syntax: CALL Parser(SearchFor$, SearchIn$, ParArray$(), ErrCode)

        Remarks: This will take a string and look for the character specified
        and store the data in the array, it then repeats this process over
        and over until the end of the string has been reached. This can be
        handy to store numbers in a compact form for storage in a file.

        Parameters Passed:
                SearchFor$ - The string (delimiter) to search for

                SearchIn$ - The string to search in and to parse

        Parameters Returned:
                ParArray$() - Contains the data from SearchIn$ but separated

                ErrCode - Will greater than 1 is a error occurred

        Example:
                SearchFor$ = "*"
                SearchIn$ = "100*200*300*400*500*"
                CALL Parser(SearchFor$, SearchIn$, ParArray$(), ErrCode)
                FOR X = 1 TO 5
                   CALL Send(ParArray$(X), No, Yes, 10)
                NEXT
                ' This would output:
                ' 100
                ' 200
                ' 300
                ' 400
                ' 500


        RandNum

        Purpose: To generate a random number within a specified range

        Syntax: Number = RandNum(Low, High)

        Remarks: This is handy to generate a random number in the range
        that you need it. It will generate a completely random number.

        Parameters Passed:
                Low - The lowest number desired

                High - The highest number desired

        Parameters Returned:
                Number - The random number generated

        Example:
                CALL Send("The number is "+STR$(RandNum(10,20)), No, Yes, 10)


        ReadUsers

        Purpose: To read from the PCBoard 14.x users file

        Syntax: CALL ReadUsers(ErrCode)

        Remarks: This will read the user's record from the PCBoard user file
        specified in the global variable UserFile$. The data will be read into
        the global type declaration UserBlock (Which is shown in Appendix D -
        Variable Reference). For other bbs types, most of the data is loaded
        directly from the bbs interface file, and calling a routine to read
        the users file is not necessary. The best way to set UserFile$ is
        to add on another line to the configuration file and read it in
        yourself after the first call to ClrScrn.

        Parameters Passed: None

        Parameters Returned:
                ErrCode - This is the error code is a error occurred
                          1 - Users file not found
                          2 - Wrong BBS type
                          3 - UserFile$ not set to Drive/Path/Filename of users
                              file

        Example:
                See BLCKDEMO.BAS

                ' UserFile$ already set earlier in the program
                CALL ReadUsers(ErrCode)
                CALL Send("You're from "+STR$(UserBlock.CityState), No,Yes,10)

        See Also: WriteUsers


        Sorter

        Purpose: To sort numbers into descending order

        Syntax: CALL Sorter(ParArray$(), Number.To.Sort)

        Remarks: If you need to sort numbers parsed with parser, or other
        numbers in a STRING array, then call this routine and it will
        sort it into a descending order.

        Parameters Passed:
                ParArray$() - The array of numbers to be sorted

                Number.To.Sort - The number of array elements to sort

        Parameters Returned:
                ParArray$() - The sorted array

        Example:
                ParArray$(1) = "400"
                ParArray$(2) = "200"
                ParArray$(3) = "600"
                CALL Sorter(ParArray$(), 3)
                FOR X=1 TO 3
                   CALL Send(ParArray$(X), No, Yes, 10)
                NEXT X
                ' Output would be this:
                ' 600
                ' 400
                ' 200


        SysopPage

        Purpose: To page the sysop if the page bell is on

        Syntax: CALL SysopPage(Answered)

        Remarks: This routine will check the page bell, and if on, will
        page the sysop using the paging sounds. If the page wasn't answered
        or the sysop isn't around then it will return a 0 in the parameter.
        This routine is affect by several global variables, which are:
                PageSound.1 - Sound #1 to be in the "beep" sound of the page

                PageSound.2 - Sound #2 to be in the "beep" sound of the page

                PageSound.3 - Sound #3 to be in the "beep" sound of the page

                Page.String$ - String to show while paging the sysop

                Not.Around$ - String to show when the sysop is not around

        Parameters Passed: None

        Parameters Returned:
                Answered - If the page was answered
                           (1 = Yes  0 = No)

        Example:
                CALL SysopPage(Answered)


        TimeConvert

        Purpose: To convert from two variables into the HH:MM format

        Syntax: CALL TimeConvert(Hours, Minutes, NewTime$)

        Remarks: This will combine hours and minutes into the HH:MM format.

        Parameters Passed:
                Hours - The hour

                Minutes - The minute

        Parameters Returned:
                NewTime$ - The hour and minute in HH:MM format

        Example:
                Hours = 10
                Minutes = 30
                CALL TimeConvert(Hours, Minutes, NewTime$)
                CALL Send(NewTime$+" is the next event time.", No, Yes, 10)

        See Also: GetTime


        ViewFile

        Purpose: To display a file to the local and remote screens

        Syntax: CALL ViewFile(FileName$, ANSICheck, MorePrompts, ExitPrompt)

        Remarks: This will display a ANSI or non-ANSI screen to both screens.
        If you specify to check for a ANSI version of the file, then Door
        Source will take the filename given, add a G to it, and look for
        the existence of that file for ANSI users. You can enable more
        prompts for documentation, or leave them off for long ANSI screens.
        The exit prompt is a "Press [ANY KEY] to continue" prompt that
        is display at the end of the file if told to do so. The user can
        abort the screen at any point by pressing the space bar, CTRL-X, or
        CTRL-K. If the No.Abort global variable is set to 1 (Yes) then
        the user can't abort the display. ANSI files should NOT exceed
        80 characters in length per line.

        Parameters Passed:
                FileName$ - Drive/Path/Filename of file to display

                ANSICheck - Check for ANSI version of file for ANSI users
                            (1 = Yes  0 = No)

                MorePrompts - Display more prompts every 23 lines
                              (1 = Yes  0 = No)

                ExitPrompts - Displays a "Press [ANY KEY]" prompt at end of
                              display (1 = Yes  0 = No)

        Parameters Returned: None

        Example:
                FileName$ = "MYFILE"
                CALL ViewFile(FileName$, Yes, No, Yes)
                FileName$ = "MYDOCS.DOC"
                CALL ViewFile(FileName$, No, Yes, Yes)


        WaitASec

        Purpose: To delay the program the specified number of seconds

        Syntax: CALL WaitASec(Number.Of.Seconds)

        Remarks: Using the SLEEP command, or a FOR loop to delay a program
        isn't often a good idea in a door because the user could drop carrier.
        This routine will delay the program correctly for the number of
        seconds specified and will also keep track of the carrier signal.

        Parameters Passed:
                Number.Of.Seconds - Number of seconds to delay program

        Parameters Returned: None

        Example:
                CALL WaitASec(5)        ' delay 5 seconds


        Windows

        Purpose: To draw window on the local and remote screens

        Syntax: CALL Windows(ULR, ULC, LRR, LRC, Fore, Back, Border, Shadow)

        Remarks: This will draw a border enclosed area on the screen, and
        will even make a shadow if requested. Printing and input is done
        inside the window with WindowPrint and WindowInput. This is a
        ANSI only routine, and shouldn't be used with non-ANSI users.

        Parameters Passed:
                ULR - Upper Lefthand row

                ULC - Upper Lefthand column

                LRR - Lower Righthand row

                LRC - Lower Righthand column

                Fore - Foreground color to use for border

                Back - Background color to use for border and to fill inside

                Border - The border number
                         1 - Single line
                         2 - Double line
                         3 - Double horizontal, Single vertical
                         4 - Single horizontal, Double vertical

                Shadow - Makes a shadow on the window
                         (1 = Yes  0 = No)

        Parameters Returned: None

        Example:
                ULR = 10: ULC = 10
                LRR = 20: LRC = 70
                CALL Windows(ULR, ULC, LRR, LRC, 11, 1, 4, Yes)

        See Also: WindowInput, WindowPrint


        WriteUsers

        Purpose: To write to PCBoard 14.x user file

        Syntax: CALL WriteUsers(ErrCode)

        Remarks: This will write the user's record to the PCBoard user file
        specified in the global variable UserFile$. The data written will be
        from the global type declaration UserBlock (Which is shown in Appendix
        D - Variable Reference). For other bbs types, most of the data is
        written when ExitDoor is called, and calling a routine to write to
        the users file is not necessary. The best way to set UserFile$ is
        to add on another line to the configuration file and read it in
        yourself after the first call to ClrScrn.

        Parameters Passed: None

        Parameters Returned:
                ErrCode - This is the error code is a error occurred
                          1 - Users file not found
                          2 - Wrong BBS type
                          3 - UserFile$ not set to Drive/Path/Filename of users
                              file

        Example:
                See BLCKDEMO.BAS

                ' UserFile$ already set earlier in the program
               UserBlock.CityState = "Anytown, USA"
               CALL ReadUsers(ErrCode)

        See Also: ReadUsers


        BlockSend

        Purpose: To send a large amount of information to both displays

        Syntax: CALL BlockSend(Array$(), Center, Lines.To.Send)

        Remarks: This will send a large pre-programmed amount of data
        to the local and remote displays. Color can only be set and
        changed via @X codes. This routine is good for programmed in
        documentation, or menus.

        Parameters Passed:
                Array$() - The array to be displayed

                Center - Center text to be displayed

                Lines.To.Send - Number of array elements to display

        Parameters Returned: None

        Example:
                Array$(1) = "This will be displayed"
                Array$(2) = "Using the BlockSend routine"
                CALL BlockSend(Array$(), No, 2)

        See Also: ColorEasy, RainbowSend, Send, QSend


        WindowPrint

        Purpose: To display text inside of a window

        Syntax: CALL WindowPrint(Text$, Row, Col, Fore, Back)

        Remarks: This is an easy way of displaying text anywhere inside of
        a window made with the Windows routine. It can also be used for
        quick short displays that aren't at the current cursor location.

        Parameters Passed:
                Text$ - Text to be displayed

                Row - Row to display at (horizontal)

                Col - Column to display at (vertical)

                Fore - Foreground color to display with

                Back - Background color to display with

        Parameters Returned: None

        Example:
                Text$ = "This will be displayed"
                Row = 12: Col = 12: Fore = 15: Back = 1
                CALL WindowPrint(Text$, Row, Col, Fore, Back)

        See Also: Windows, WindowInput


        WindowInput

        Purpose: To display a prompt and get input from inside a window

        Syntax: CALL WindowInput(Text$, MaxLength, Row, Col, Fore, Back)

        Remarks: This works just like the Incomm routine, but does the
        I/O inside of a window created with the Windows routine. The
        MaxLength should be just right so that input won't overflow the
        window border and cause problems with erasing it.

        Parameters Passed:
                Text$ - Prompt to be displayed

                MaxLength - Maximum number of characters allowed in input

                Row - Row to display at (horizontal)

                Col - Column to display at (vertical)

                Fore - Foreground color to display prompt in

                Back - Background color to display prompt in

        Parameters Returned:
                ARG$ - The input received

        Example:
                Text$ = "Enter your name:"
                MaxLength = 25: Row = 13: Col = 12
                Fore = 15: Back = 1
                CALL WindowInput(Text$, MaxLength, Row, Col, Fore, Back)

        See Also: Windows, WindowPrint


        RainbowSend

        Purpose: To display text in a color, rainbow like form

        Syntax: CALL RainbowSend(Text$, Bell, Enter, Color.To.Use)

        Remarks: This is a creative way to display text to both displays.
        It will take the color given to use, and rotate through the colors
        making a very colorful display. Experiment with different colors
        to find the most desirable effect.

        Parameters Passed:
                Text$ - Text to be displayed

                Bell - Sound the remote speaker, and local is page bell is on

                Enter - Send a CR/LF sequence once displaying is done

                Color.To.Use - Foreground color to display text in

        Parameters Returned: None

        Example:
                Text$ = "This will be displayed"
                CALL RainbowSend(Text$, No, Yes, 10)

        See Also: BlockSend, ColorEasy, Send, QSend


        PromptIncomm

        Purpose: To provide a very formatted input field with a prompt

        Syntax: CALL PromptIncomm(Text$, Default$, DefaultColor, MaxLength,
                Color.To.Use)

        Remarks: This will make a little ( ) area for input to be inside of
        for ANSI users, non-ANSI users will just have a regular prompt. This
        routine also allows to easily add a "default" to the prompt.

        Parameters Passed:
                Text$ - Prompt to display

                Default$ - "Default" field. Some predefined ones are:
                           Default1 = (Enter=no)
                           Default2 = (Enter=none)
                           Default3 = (Enter=quits)

                DefaultColor - Foreground color for default text

                MaxLength - Maximum number of characters (Required to be
                            greater than 0)

                Color.To.Use - Foreground color for prompt

        Parameters Returned:
                ARG$ - The input received

        Example:
                See PRMTDEMO.BAS

                Text$ = "Enter your name"
                CALL PromptIncomm(Text$, Default3, 15, 10, 11)
                IF AllTrun$(ARG$) = "" THEN
                   ' Process default
                ELSE
                   ' Process other
                END IF
                ' This would output
                ' Enter your name (Enter=quits) ? (         )
                ' The input would be displayed inside the ( )

        See Also: EntryIncomm, Incomm


        EntryIncomm

        Purpose: To provide a field showing maximum length of input for prompt

        Syntax: CALL EntryIncomm(Text$, MaxLength, FieldColor, Color.To.Use)

        Remarks: This is a handy routine to for larger fields (3 characters and
        larger) that lets the user know what the limit is on the field size by
        printing above the prompt a (------) field indicator showing the
        maximum number of characters allowed.

        Parameters Passed:
                Text$ - Prompt to display

                MaxLength - Maximum number of characters to allow for input
                            (Required to be greater than 1)

                FieldColor - The color of the (---) field above the prompt

                Color.To.Use - The foreground color for the prompt itself

        Parameters Returned:
                ARG$ - The input received

        Example:
                See PRMTDEMO.BAS

                Text$ = "Enter your name:"
                CALL EntryIncomm(Text$, 20, 10, 11)
                ' This would output
                '                (--------------------)
                ' Enter your name:

        See Also: PromptIncomm, Incomm


        ShellToDOS

        Purpose: To efficiently shell to DOS in order to avoid conflicts

        Syntax: CALL ShellToDOS(Shell.String$)

        Remarks: This will let Door Source completely wrap up all of its
        operations (actually close the com port, but uphold DTR and carrier)
        so that shelling to a external file transfer program is possible
        without a conflict of interrupts. This command duplicates what
        a SHELL command would do in BASIC, but gives Door Source a chance
        to clean up itself.

        Parameters Passed:
                Shell.String$ - This is the command to be executed once the
                                shell is started

        Parameters Returned: None

        Example:
                Shell.String$ = "DIR >OUTPUT.TXT"
                CALL ShellToDOS(Shell.String$)




                ░▒▓                                      ▓▒░
                ░▒▓ End of Door Source 4.0 Documentation ▓▒░
                ░▒▓                                      ▓▒░